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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: rewrite the Localization guide to the complete-reference template
yhh21bc69d8e110
diff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/guides/localization.mdxindex 639189aab..524b0b7e6 100644--- a/docs/astro/src/content/docs/guides/localization.mdx+++ b/docs/astro/src/content/docs/guides/localization.mdx@@ -1,41 +1,73 @@---title: Localization-description: Multi-language text with Res(Localization).+description: The complete guide to i18n — translation catalogs, interpolation, plurals, and locale switching via Res(Localization).---import { Aside } from '@astrojs/starlight/components';Register a translation catalog per locale, switch the active locale, and look up-strings with `t()` — all through the `Localization` resource.+strings with `t()` — all through the `Localization` resource. It's deliberately+`Intl`-free so behavior is identical on the web and WeChat.-## Catalogs and translation+## Catalogs & translation```typescriptimport { defineSystem, Res, Localization } from 'esengine';const setupI18n = defineSystem([Res(Localization)], (i18n) => {i18n.addCatalog('en', { play: 'Play', score: 'Score: {n}' });- i18n.addCatalog('zh-CN', { play: '开始', score: '得分:{n}' });+ i18n.addCatalog('zh-CN', { play: '开始', score: '得分:{n}' });i18n.setLocale('zh-CN');- const label = i18n.t('score', { n: 42 }); // "得分:42"+ const label = i18n.t('score', { n: 42 }); // "得分:42"});```-- **`addCatalog(locale, entries)`** merges keys into a locale — call it again to- add more (later calls override).-- **`t(key, params?)`** interpolates `{placeholder}` values. If the key is missing- it falls back to the fallback locale, then to the key itself.-- Also: `setLocale`, `setFallbackLocale`, `availableLocales()`, `has(key)`.+- **`addCatalog(locale, entries)`** merges keys into a locale — call it again to add+ more (later calls override).+- **`t(key, params?)`** interpolates `{placeholder}` values. Missing keys fall back to+ the fallback locale, then to the key itself (a visible, greppable fallback).## PluralsA catalog entry can carry plural forms (`zero` / `one` / `other`); `t` selects the-right one from a `count` parameter, and you can register a per-locale plural-selector for languages whose rules differ from the default.+right one from a `count` param. Register a per-locale selector for languages whose+rules differ from the default English-style one.++```typescript+i18n.addCatalog('en', { apples: { one: '{count} apple', other: '{count} apples' } });+i18n.t('apples', { count: 3 }); // "3 apples"+```++## `Localization` reference++| Method | Description |+|---|---|+| `addCatalog(locale, entries)` | Merge translation keys into a locale. |+| `t(key, params?)` | Look up + interpolate a string. |+| `setLocale(locale)` | Set the active locale. |+| `setFallbackLocale(locale)` | Set the locale used when a key is missing. |+| `setPluralSelector(locale, selector)` | Custom plural rule for a locale. |+| `availableLocales()` | List registered locales. |+| `has(key)` | Whether a key exists in the active/fallback locale. |++## Best practices++- **Key everything through `t()`** — 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.<Aside type="tip">- Localization is a per-App service, so switching the locale updates every `t()`- lookup from that point on — re-run the systems that build your text (or read- `t()` each frame where the text can change).+ 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.</Aside>++## See also++- [UI](/docs/guides/ui/) — bind `Text` to translated keys.+- [Assets](/docs/guides/assets/) — ship string tables as assets.diff --git a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx b/docs/astro/src/content/docs/zh-cn/guides/localization.mdxindex 95ef4ace9..36c46b701 100644--- a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx@@ -1,12 +1,12 @@---title: 本地化-description: 用 Res(Localization) 做多语言文本。+description: i18n 完整指南——翻译目录、插值、复数与语言切换,通过 Res(Localization)。---import { Aside } from '@astrojs/starlight/components';-为每个 locale 注册一份翻译目录(catalog),切换当前 locale,并用 `t()` 查字符串——都-通过 `Localization` 资源完成。+为每个 locale 注册一份翻译目录(catalog),切换当前 locale,并用 `t()` 查字符串——都通过+`Localization` 资源完成。它刻意不依赖 `Intl`,所以在 Web 与微信上行为一致。## 目录与翻译@@ -15,25 +15,53 @@ import { defineSystem, Res, Localization } from 'esengine';const setupI18n = defineSystem([Res(Localization)], (i18n) => {i18n.addCatalog('en', { play: 'Play', score: 'Score: {n}' });- i18n.addCatalog('zh-CN', { play: '开始', score: '得分:{n}' });+ i18n.addCatalog('zh-CN', { play: '开始', score: '得分:{n}' });i18n.setLocale('zh-CN');- const label = i18n.t('score', { n: 42 }); // "得分:42"+ const label = i18n.t('score', { n: 42 }); // "得分:42"});```-- **`addCatalog(locale, entries)`** 把 key 合并进某个 locale——可多次调用追加(后面的- 会覆盖)。-- **`t(key, params?)`** 会插值 `{placeholder}` 的值。若 key 缺失,则回退到 fallback- locale,再回退到 key 本身。-- 还有:`setLocale`、`setFallbackLocale`、`availableLocales()`、`has(key)`。+- **`addCatalog(locale, entries)`** 把 key 合并进某个 locale——可多次调用追加(后面的会覆盖)。+- **`t(key, params?)`** 会插值 `{placeholder}` 的值。缺失的 key 回退到 fallback locale,再回退+ 到 key 本身(一个可见、可 grep 的兜底)。## 复数-目录条目可以携带复数形式(`zero` / `one` / `other`);`t` 会根据 `count` 参数选出正确的-那个,你还能为规则不同的语言注册按 locale 的复数选择器。+目录条目可以携带复数形式(`zero` / `one` / `other`);`t` 会根据 `count` 参数选出正确的那个。+为规则与默认英语式不同的语言注册按 locale 的选择器。++```typescript+i18n.addCatalog('en', { apples: { one: '{count} apple', other: '{count} apples' } });+i18n.t('apples', { count: 3 }); // "3 apples"+```++## `Localization` 参考++| 方法 | 说明 |+|---|---|+| `addCatalog(locale, entries)` | 把翻译 key 合并进某个 locale。 |+| `t(key, params?)` | 查找 + 插值一个字符串。 |+| `setLocale(locale)` | 设置当前 locale。 |+| `setFallbackLocale(locale)` | 设置 key 缺失时使用的 locale。 |+| `setPluralSelector(locale, selector)` | 为某 locale 设自定义复数规则。 |+| `availableLocales()` | 列出已注册的 locale。 |+| `has(key)` | key 是否存在于当前/回退 locale。 |++## 最佳实践++- **一切都经 `t()`**——绝不硬编码面向用户的字符串,连占位符也不。+- **插值,别拼接**(`'Score: {n}'`),这样语序能因语言而异。+- **设一个回退 locale**,让缺失的翻译退化到另一种语言,而不是裸 key。+- **locale 变化时重跑构建文本的系统**,或在文本会变的地方每帧读 `t()`——切换 locale 会更新+ 之后每一次查询。<Aside type="tip">- 本地化是逐 App 的服务,所以切换 locale 后,从那一刻起每次 `t()` 查询都会更新——重新- 运行搭建文本的系统(或在文本会变化的地方每帧读 `t()`)。+ 本地化是逐 App 的服务,所以切换 locale 会更新之后每一次 `t()` 调用。把 UI 的 `Text.content`+ 绑到 key,切换语言就会重排 UI。</Aside>++## 参见++- [UI](/docs/zh-cn/guides/ui/) —— 把 `Text` 绑到翻译 key。+- [资源](/docs/zh-cn/guides/assets/) —— 把字符串表作为资源发布。