Documentation
¶
Overview ¶
Package i18n is the module-side internationalization loader for the SDK.
A module ships nested JSON catalogs (one file per locale, e.g. i18n/en-US.json, i18n/zh-TW.json) and registers them once at startup via RegisterMessages. Catalogs are flattened to dotted keys so a nested object like {"permissions":{"users.read":"View users"}} becomes the key "permissions.users.read".
The catalogs feed Label values (Text / T). Labels are opaque: they carry either a literal string or a catalog key, and resolution to a per-locale map happens lazily — typically at manifest build time when a permission is declared (ms.RegisterPermission). This package never resolves at call time, so the order of RegisterMessages vs. building Labels does not matter as long as both run before the manifest is served.
The registry is a process-global keyed by locale → flatKey → message. A MirrorStack module is a single binary serving a single module identity, so one global catalog per process is the right grain. Tests can call Reset to clear it.
Index ¶
Constants ¶
const DefaultLocale = "en-US"
DefaultLocale is the fallback locale. Literal Text() labels resolve under this locale, and catalog T() labels fall back to it (then to the raw key) when no loaded locale carries the requested message.
Variables ¶
This section is empty.
Functions ¶
func Locales ¶
func Locales() []string
Locales returns the sorted list of locales currently loaded. Test/debug aid.
func Lookup ¶
Lookup returns the locale → message map for a catalog key. Unlike Label.Resolve it does NOT fall back to the raw key — an undeclared key yields an empty map, so callers (e.g. manifest defaults) can omit the field entirely and let a literal fallback win. The returned map is owned by the caller.
func LookupList ¶
LookupList resolves a catalog key whose per-locale value packs a LIST of items into one delimited string, returning locale → []item. Each locale's value is split on sep and every element is space-trimmed; empty elements are dropped, and a locale that yields no items is omitted. Like Lookup (and unlike Label.Resolve) it does NOT fall back to the raw key — an undeclared key yields an empty map, so a caller (e.g. manifest defaults) can omit the field and let a non-localized default win.
It is the list counterpart of Lookup: Lookup(module.name)→NameLabels (one display string per locale), LookupList(module.tags, ",")→TagLabels (a tag LIST per locale). The delimited-string convention exists because message catalogs are string-valued — flatten() ignores JSON array leaves — so an author packs a tag list as e.g. en-US "Auth, Payments" / zh-TW "驗證, 付款". The returned map is owned by the caller.
func RegisterMessages ¶
RegisterMessages loads every <dir>/<locale>.json file from fsys into the process-global catalog. The locale is the filename without its .json extension (e.g. "en-US", "zh-TW"). Each file must be a nested JSON object; it is flattened to dotted keys (a nested {"a":{"b":"x"}} becomes "a.b").
Re-registering a locale merges into any existing entries for that locale (last write wins per key), so a module may load multiple catalog dirs. Returns an error if a file can't be read or isn't a JSON object; files that are not *.json (or are sub-directories) are skipped.
//go:embed i18n/*.json var i18nFS embed.FS ms.RegisterMessages(i18nFS, "i18n")
Types ¶
type Label ¶
type Label struct {
// contains filtered or unexported fields
}
Label is an opaque, deferred-resolution display string. Construct one with Text (a literal) or T (a catalog key). Resolution to a per-locale map happens later via Resolve, reading the catalog registered by RegisterMessages.
func T ¶
T returns a catalog-key Label. At Resolve time it is looked up per loaded locale (skipping locales that lack the key). If no loaded locale carries the key, it falls back to {DefaultLocale: key} — the raw key, NOT a humanized form — so a missing translation is unambiguous.
func Text ¶
Text returns a literal Label. It resolves to {DefaultLocale: s}, ignoring the catalog — use it for strings that are not translated (or whose translation lives elsewhere).
func (Label) IsZero ¶
IsZero reports whether the Label was never set (the zero value). Callers use this to omit empty Labels from the manifest (e.g. an undeclared Description).
func (Label) Resolve ¶
Resolve returns the locale → message map for this Label, reading the catalog registered via RegisterMessages.
- A literal Text(s) resolves to {DefaultLocale: s}.
- A catalog T(key) resolves to {locale: messages[locale][key]} for every loaded locale that has the key; locales missing the key are skipped. If NO loaded locale has it, it falls back to {DefaultLocale: key}.
The returned map is freshly allocated and owned by the caller.
Source Files