SCUA

How-to

Set the locale and timezone

A program can read the locale and timezone it's running under, and you can set both at launch — which is exactly what you want for testing date/time formatting and localized output against a fixed environment.

Unlike environment variables, these need no capability grant: they're descriptive settings, not authority. They're read through the sys module:

import sys

print(sys.locale())     -- a BCP-47 tag, e.g. "de-DE"; "und" when unset
print(sys.timezone())   -- UTC offset in minutes, e.g. 120 for +02:00; 0 (UTC) when unset

#Neutral by default

With no override, the locale is "und" (undetermined) and the timezone is UTC (offset 0). This is deliberate: a run is then reproducible across machines and CI, and a save-and-reload sees the same values. SCUA does not silently read your machine's locale — that would make programs behave differently on different computers, and a server rendering content for many users almost never wants its own machine's locale anyway.

So "detect the device locale" is opt-in, not automatic (see below).

#Overriding at launch

scua --locale=de-DE --tz=+02:00  app.scua    # pin both — the testing workhorse
scua --tz=+05:45                  app.scua    # non-hour offsets work (Nepal)
scua --tz=UTC                     app.scua    # explicit UTC
  • --locale=<tag> takes any BCP-47 string (en-US, fr, ja-JP); it's stored as-is.
  • --tz=<offset> accepts ±HH:MM, ±HH, and UTC/Z. IANA zone names like Europe/Berlin are not supported — pass the offset instead. (There's no timezone database, so there's no DST either; an offset is a fixed shift from UTC.)

When embedding SCUA in a host program, the host sets these per partition through its API instead of CLI flags — so a game server can give each player their own locale and offset.

#Reading the real device setting

To pick up the actual machine locale/timezone, ask for it explicitly with host:

scua --locale=host --tz=host  app.scua

--locale=host reads LC_ALL / LC_CTYPE / LANG and normalizes e.g. de_DE.UTF-8 to de-DE. --tz=host reads a numeric TZ offset — if your system only exposes a zone name, pass --tz=±HH:MM explicitly. This host source is the single, opt-in point where a run depends on the environment (much like --fast for the clock); everything else stays reproducible.

#Using the timezone with dates

The timezone offset feeds the date layer: time.now() and time.of(...) default to it, so civil readings come out in the program's configured zone.

import sys
import time

-- With `--tz=+02:00`, this prints the instant at +02:00; with no flag, at UTC.
let t = time.at(1_782_741_909_123, sys.timezone())
print(t.iso())

Pin --tz (and --locale) in your tests so date formatting and any locale branches are deterministic regardless of where the tests run. See examples/locale.scua for a runnable version.