l10n
game/l10n provides game localization built on NSGo's core package and the Go standard library: JSON string tables with BCP-47 fallback and CLDR plurals, script-aware FontSet[F], RTL visual reordering and HUD mirroring, and per-language asset catalogs with selective group reloads.
import "github.com/nsgo-dev/game/packages/game/l10n"
String tables, interpolation, and CLDR plurals
Load flat, nested, or CLDR plural JSON tables into a Catalog with a fallback locale, then wrap it in a reactive Localizer bound to a *core.Scope:
cat := l10n.NewCatalog("en")
_ = cat.LoadJSON("en", []byte(`{
"menu": {"play": "Play"},
"hud": {"score": "Score: {score}"},
"coins": {"zero": "No coins", "one": "{count} coin", "other": "{count} coins"}
}`))
_ = cat.LoadJSON("zh-Hans", []byte(`{
"menu": {"play": "开始游戏"},
"hud": {"score": "得分:{score}"},
"coins": {"other": "{count} 枚金币"}
}`))
loc := l10n.NewLocalizer(cx, cat)
loc.SetLocale("zh-Hans") // or omit to follow the system locale
title := loc.T("menu.play")
score := loc.T("hud.score", l10n.Param("score", 420))
coins := loc.Plural("coins", 3)
_, _, _ = title, score, coins
Lookups walk the normalized BCP-47 fallback chain (for example zh-Hans-CN -> zh-Hans -> zh -> fallback locale) and return the key itself if missing everywhere. You can also populate entries programmatically via cat.Set and cat.SetPlural.
Script-aware FontSet[F]
Pair mixed-script text with per-script or per-locale fonts (any font type F, such as *text.BitmapFont or core.Font):
fonts := l10n.NewFontSet(latinFont)
fonts.SetScript(l10n.ScriptCJK, cjkFont)
fonts.SetScript(l10n.ScriptArabic, arabicFont)
fonts.SetLocale("ja", jpFont)
// Split mixed strings into contiguous runs, each paired with its resolved font:
runs := fonts.RunsForText(loc.Locale(), "Score: 120 得分")
for _, run := range runs {
drawRun(run.Text, run.Font)
}
Inspect scripts directly with RuneScript, DetectScript, SegmentByScript, and LocaleScript.
RTL visual ordering and layout mirroring
Query text direction from a locale (LocaleDirection), scope (EnvDirection), or string (TextDirection). For custom canvas text renderers that draw glyphs left-to-right, convert logical strings to visual order with VisualOrder (or loc.Visual(s)):
dir := loc.Direction()
visual := loc.Visual(loc.T("hud.greeting"))
aligned := l10n.LayoutAlignment("start", dir) // "left" in LTR, "right" in RTL
x := l10n.MirrorX(16, iconW, screenW, dir)
_, _, _ = visual, aligned, x
Per-language asset catalogs
Manage localized voiceovers, textures, or title banners with AssetCatalog, discovered automatically from an io/fs.FS (locales/<locale>/<name>, <name>.<locale>.<ext>, or <name>_<locale>.<ext>) or loaded from a JSON manifest:
assets, err := l10n.DiscoverFS(embedFS, "en")
if err != nil {
return err
}
assets.RegisterGroup("voice", "voice/intro.wav", "voice/boss.wav")
// Reload only asset groups whose resolved paths actually change on language switch:
stop := assets.OnReload(func(groups []string, locale string) {
reloadAssetGroups(groups, locale)
})
defer stop()
assets.SetLocale("ja")
resolved, ok := assets.Resolve("voice/intro.wav", assets.Locale())
_, _ = resolved, ok
// Audit missing variants in tests or CI:
for _, rep := range assets.CheckMissing("ja", "zh-Hans", "ar") {
if !rep.Complete() {
log.Printf("%s missing %v (%.0f%%)", rep.Locale, rep.Missing, rep.Coverage*100)
}
}
Use assets.WatchLocale(cx, localeSignal, reloadFn) to connect locale changes directly to a reactive core.Signal[string].