Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs(i18n): string tables + Text binding replace the manual workaround, EN+zh

yhh3852a46bc7e2
diff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/guides/localization.mdx
index fd6a7d496..4b22a2e68 100644
--- a/docs/astro/src/content/docs/guides/localization.mdx
+++ b/docs/astro/src/content/docs/guides/localization.mdx
@@ -69,23 +69,63 @@ i18n.t('apples', { count: 3 }); // "3 apples"
| `availableLocales()` | List registered locales. |
| `has(key)` | Whether a key exists in the active/fallback locale. |
+## String tables (`.eslocale`)
+
+Translations can ship as **data** instead of code: a `.eslocale` asset carries ONE
+locale's catalog, so a game loads only the languages it needs.
+
+```json
+// assets/i18n/zh-CN.eslocale
+{
+ "version": 1,
+ "locale": "zh-CN",
+ "entries": {
+ "ui.title": "UI 控件",
+ "apples": { "other": "{count} 个苹果" }
+ }
+}
+```
+
+Create one in the editor (Content Browser → right-click → **New Locale Table**) or
+by hand. Load explicitly with `Assets.loadLocaleTable(path)` (requires the
+localization plugin — it fails loud otherwise), preload via
+`new LocalizationPlugin({ tables: ['assets/i18n/zh-CN.eslocale'] })`, or let the
+[Text binding below](#bind-ui-text-to-keys) load everything automatically. The
+export cook always ships `.eslocale` files — they load by key, so reachability
+can't see them and force-includes them instead.
+
+## Bind UI Text to keys
+
+Set `Text.i18nKey` (the **I18n Key** dropdown in the editor's Details panel, listing
+every key across the project's tables with a translated preview) and `content`
+becomes derived: it re-resolves **every frame**, so `setLocale` — or a table landing
+late — re-flows every bound label with no code. Scene-driven projects get the whole
+loop for free: a scene that binds any key auto-installs the plugin at load, loads
+every shipped table, and starts in the **player's system language** when a matching
+table ships (a game that installs the plugin itself, or calls `setLocale`, is never
+overridden).
+
+Keep **dynamic** labels (`Score: 42`) code-driven — bound content is derived, so a
+label your code rewrites must not also carry a key; call `t('score', { n })` in the
+system that owns it instead.
+
## Best practices
-- **Key everything through `t()`** — never hard-code user-facing strings, even
- placeholders.
+- **Key everything through `t()` or `i18nKey`** — never hard-code user-facing
+ strings, even placeholders.
- **Interpolate, don't concatenate** (`'Score: {n}'`), so word order can differ per
language.
- **Set a fallback locale** so a missing translation degrades to another language
rather than a raw key.
-- **Re-run text-building systems on locale change**, or read `t()` each frame where
- text can change — switching the locale updates every subsequent lookup.
+- **One `.eslocale` per language**, all in one folder (`assets/i18n/`), keyed
+ identically — a missing key falls back visibly to the key string.
<Aside type="tip">
- Localization is a per-App service, so switching the locale updates every later
- `t()` call. Bind UI `Text.content` to keys so a language switch re-flows the UI.
+ See `examples/ui-controls` for the zero-code loop: five labels bound by
+ `i18nKey`, `en` + `zh-CN` tables, and no localization code at all.
</Aside>
## See also
-- [UI](/docs/guides/ui/) — bind `Text` to translated keys.
-- [Assets](/docs/guides/assets/) — ship string tables as assets.
+- [UI](/docs/guides/ui/) — the `Text` component the binding rides on.
+- [Assets](/docs/guides/assets/) — how assets ship and load.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
index ed7e80f09..6ccce6494 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
@@ -64,20 +64,54 @@ i18n.t('apples', { count: 3 }); // "3 apples"
| `availableLocales()` | 列出已注册的 locale。 |
| `has(key)` | key 是否存在于当前/回退 locale。 |
+## 字符串表(`.eslocale`)
+
+翻译可以作为**数据**发布,而不是写死在代码里:一个 `.eslocale` 资产装着一种语言的目录,
+游戏只加载它需要的语言。
+
+```json
+// assets/i18n/zh-CN.eslocale
+{
+ "version": 1,
+ "locale": "zh-CN",
+ "entries": {
+ "ui.title": "UI 控件",
+ "apples": { "other": "{count} 个苹果" }
+ }
+}
+```
+
+在编辑器里创建(内容浏览器 → 右键 → **新建本地化表**)或手写皆可。显式加载用
+`Assets.loadLocaleTable(path)`(需要本地化插件——否则大声报错),预载用
+`new LocalizationPlugin({ tables: ['assets/i18n/zh-CN.eslocale'] })`,或者让
+[下面的 Text 绑定](#把-ui-text-绑到-key)全自动加载。导出 cook 永远会把 `.eslocale`
+打进包里——它们按 key 加载,可达性分析看不见它们,所以强制收入。
+
+## 把 UI Text 绑到 key
+
+设置 `Text.i18nKey`(编辑器细节面板里的 **I18n Key** 下拉,列出项目全部表里的 key 及其
+译文预览),`content` 就变成派生值:**每帧**重新解析,所以 `setLocale`——或者一张晚到的
+表——都会让所有绑定的标签自动重排,零代码。场景驱动的项目免费得到整条链路:只要场景里
+有任何绑定的 key,加载时会自动安装插件、加载全部已发布的表,并在有匹配的表时以
+**玩家的系统语言**启动(自己安装插件、或调用过 `setLocale` 的游戏永远不会被覆盖)。
+
+**动态**标签(`Score: 42`)请保持代码驱动——绑定的 content 是派生的,代码会改写的标签
+不能同时携带 key;在拥有它的系统里调 `t('score', { n })` 即可。
+
## 最佳实践
-- **一切都经 `t()`**——绝不硬编码面向用户的字符串,连占位符也不。
+- **一切都经 `t()` 或 `i18nKey`**——绝不硬编码面向用户的字符串,连占位符也不。
- **插值,别拼接**(`'Score: {n}'`),这样语序能因语言而异。
- **设一个回退 locale**,让缺失的翻译退化到另一种语言,而不是裸 key。
-- **locale 变化时重跑构建文本的系统**,或在文本会变的地方每帧读 `t()`——切换 locale 会更新
- 之后每一次查询。
+- **一种语言一个 `.eslocale`**,放在同一目录(`assets/i18n/`),key 完全一致——缺失的
+ key 会以 key 字符串可见地兜底。
<Aside type="tip">
- 本地化是逐 App 的服务,所以切换 locale 会更新之后每一次 `t()` 调用。把 UI 的 `Text.content`
- 绑到 key,切换语言就会重排 UI。
+ 看 `examples/ui-controls` 的零代码闭环:五个标签绑 `i18nKey`,`en` + `zh-CN` 两张表,
+ 没有一行本地化代码。
</Aside>
## 参见
-- [UI](/docs/zh-cn/guides/ui/) —— 把 `Text` 绑到翻译 key。
-- [资源](/docs/zh-cn/guides/assets/) —— 把字符串表作为资源发布。
+- [UI](/docs/zh-cn/guides/ui/) —— 绑定所依托的 `Text` 组件。
+- [资源](/docs/zh-cn/guides/assets/) —— 资产如何发布与加载。