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: add Localization guide (Res(Localization))

yhh59b164cb5c38
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 60c5db690..4c9379071 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -75,6 +75,7 @@ export default defineConfig({
{ label: 'Prefabs', translations: { 'zh-CN': '预制体' }, slug: 'guides/prefab' },
{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },
+ { label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'guides/localization' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
],
},
diff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/guides/localization.mdx
new file mode 100644
index 000000000..639189aab
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/localization.mdx
@@ -0,0 +1,41 @@
+---
+title: Localization
+description: Multi-language text with 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.
+
+## Catalogs and translation
+
+```typescript
+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.setLocale('zh-CN');
+ 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)`.
+
+## Plurals
+
+A 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.
+
+<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).
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
new file mode 100644
index 000000000..95ef4ace9
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
@@ -0,0 +1,39 @@
+---
+title: 本地化
+description: 用 Res(Localization) 做多语言文本。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+为每个 locale 注册一份翻译目录(catalog),切换当前 locale,并用 `t()` 查字符串——都
+通过 `Localization` 资源完成。
+
+## 目录与翻译
+
+```typescript
+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.setLocale('zh-CN');
+ 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)`。
+
+## 复数
+
+目录条目可以携带复数形式(`zero` / `one` / `other`);`t` 会根据 `count` 参数选出正确的
+那个,你还能为规则不同的语言注册按 locale 的复数选择器。
+
+<Aside type="tip">
+ 本地化是逐 App 的服务,所以切换 locale 后,从那一刻起每次 `t()` 查询都会更新——重新
+ 运行搭建文本的系统(或在文本会变化的地方每帧读 `t()`)。
+</Aside>