l10n
game/l10n 基于 NSGo 的 core 包和 Go 标准库提供游戏本地化能力:支持 BCP-47 回退链与 CLDR 复数规则的 JSON 字符串表、按文字脚本自动选字体的 FontSet[F]、RTL 视觉重排与 HUD 镜像,以及支持按组增量重载的多语言资源目录。
import "github.com/nsgo-dev/game/packages/game/l10n"
字符串表、插值与 CLDR 复数
向带回退语言的 Catalog 加载扁平、嵌套或 CLDR 复数格式的 JSON 表,并用绑定到 *core.Scope 的响应式 Localizer 读取翻译:
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") // 不设置时默认跟随系统语言
title := loc.T("menu.play")
score := loc.T("hud.score", l10n.Param("score", 420))
coins := loc.Plural("coins", 3)
_, _, _ = title, score, coins
查找会沿规范化后的 BCP-47 回退链逐级解析(如 zh-Hans-CN -> zh-Hans -> zh -> 回退语言),全部缺失时原样返回键名。也可以通过 cat.Set 和 cat.SetPlural 以代码方式写入词条。
按文字脚本选字体(FontSet[F])
为混合文字场景配置按脚本或按语言映射的字体集(支持任意字体类型 F,例如 *text.BitmapFont 或 core.Font):
fonts := l10n.NewFontSet(latinFont)
fonts.SetScript(l10n.ScriptCJK, cjkFont)
fonts.SetScript(l10n.ScriptArabic, arabicFont)
fonts.SetLocale("ja", jpFont)
// 将混排文本切分为连续片段,每段附带匹配好的字体:
runs := fonts.RunsForText(loc.Locale(), "Score: 120 得分")
for _, run := range runs {
drawRun(run.Text, run.Font)
}
也可直接调用 RuneScript、DetectScript、SegmentByScript 与 LocaleScript 进行脚本检测。
RTL 视觉排序与布局镜像
通过 LocaleDirection、EnvDirection 或 TextDirection 查询书写方向。对于按从左到右逐字绘制的自定义画布文本渲染器,使用 VisualOrder(或 loc.Visual(s))将逻辑字符串转为视觉顺序:
dir := loc.Direction()
visual := loc.Visual(loc.T("hud.greeting"))
aligned := l10n.LayoutAlignment("start", dir) // LTR 下为 "left",RTL 下为 "right"
x := l10n.MirrorX(16, iconW, screenW, dir)
_, _, _ = visual, aligned, x
多语言资源目录(AssetCatalog)
用 AssetCatalog 管理按语言区分的配音、贴图或标题横幅,可从任意 io/fs.FS 自动发现(支持 locales/<locale>/<name>、<name>.<locale>.<ext> 与 <name>_<locale>.<ext>),也可通过 LoadAssetManifestJSON 加载清单:
assets, err := l10n.DiscoverFS(embedFS, "en")
if err != nil {
return err
}
assets.RegisterGroup("voice", "voice/intro.wav", "voice/boss.wav")
// 切换语言时仅重载解析路径真正发生变化的资源组:
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
// 在测试或 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)
}
}
使用 assets.WatchLocale(cx, localeSignal, reloadFn) 可直接监听响应式 core.Signal[string] 并在语言切换时触发增量重载。