多语言 (i18n)¶

生态系统的产品与文档以多种语言提供。本页说明语言政策及其技术实现。

语言政策¶

层级	语言
必须	Монгол (`mn`) · English (`en`)
主要产品	+ 中文 (`zh`) · Русский (`ru`)
生态系统层面的文档	蒙古语 + 联合国六种官方语言

蒙古语是源语言——原文以蒙古语撰写，再向其他语言翻译。

联合国六种官方语言是：العربية (ar) · 中文 (zh) · English (en) · Français (fr) · Русский (ru) · Español (es)。本站（生态系统层面的文档）在蒙古语之外另提供这六种，共七种语言。

为什么恰好是这几种语言？

生态系统层面文档的读者不只是内部开发者，还包括国际合作伙伴、援助机构、标准化组织和境外集成商。联合国六种语言的全球覆盖面最广，而且是不偏向任何单一国家的中立选择。

各平台的深层技术文档（endpoint 结构、SDK 参考）不在本政策范围之内—— 它们仍在各自仓库内保持 MN + EN。

产品中的 i18n¶

应用按以下顺序判定用户语言：

用户自身的设置（保存在个人资料中）；
浏览器的 Accept-Language；
默认语言（mn）。

AI 助手以用户的语言作答——问题用哪种语言提出，就用哪种语言回答。

词典的两个层次¶

词典存放在两个地方，理解它们的边界很重要：

词典	位置	规模
共享 —— 登录、菜单、管理端、eID	`@gerege/ui-core`	846 个键 × 7 种语言
平台 —— 该业务领域的专有术语	`lib/<platform>I18n.ts`	各平台各不相同，通常 2–4 种语言

规则是：共享词典只认识共享的界面。 钱包的 IBAN／流水用语、开发者门户的 API 目录、Ring 的业务流程术语——这些都放在应用自己的词典里。

原因是成本：若把 Ring 的 1,104 条术语放进共享词典，kiosk、POS、钱包就都得背上它们，而且每新增一种语言，这份成本就翻七倍。

平台词典对尚未翻译的语言会回退到英文——因此界面可以有七种语言，而营销文案与领域术语的语言数量可以更少。

界面语言 ≠ 内容语言

把词典从四种语言扩到七种，凡是写着 Record<Lang, …> 的地方全都断了： landing 页的营销文案、API 目录的说明——这些是由人撰写的，并不像界面那样可以同步扩张。在这类地方，要把语言集合显式声明出来，例如 LANDING_LANGS。

文档中的 i18n¶

各仓库的文档站点均使用 MkDocs Material + mkdocs-static-i18n。

后缀式结构¶

翻译通过在文件名中加入语言代码来实现：

docs/
├── index.md        ← Монгол（默认）
├── index.ar.md     ← العربية
├── index.zh.md     ← 中文
├── index.en.md     ← English
├── index.fr.md     ← Français
├── index.ru.md     ← Русский
└── index.es.md     ← Español

配置：

plugins:
  - i18n:
      docs_structure: suffix
      fallback_to_default: true
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: mn
          default: true
          name: Монгол
          build: true
        - locale: en
          name: English
          build: true
        - locale: ar
          name: العربية
          build: true
        # … zh · fr · ru · es 同理

默认语言构建在站点根路径（/），其余语言构建在子路径下（/en/、/ar/、 /zh/、/fr/、/ru/、/es/）。

回退（fallback）¶

fallback_to_default: true——未翻译的页面会显示默认语言的内容。因此即使翻译尚不齐全，站点依然完整，不会出现 404。

这是务实的选择：文档持续增加，翻译总是滞后。若非要等所有页面同时译完，就等于根本不发布文档。

导航翻译¶

菜单标题不在页面正文里，而在 mkdocs.yml 中，因此需要为每个 locale 单独翻译：

        - locale: en
          nav_translations:
            Архитектур: Architecture
            Платформууд: Platforms
        - locale: ar
          nav_translations:
            Архитектур: البنية المعمارية
            Платформууд: المنصّات

新增页面时若忘了给全部六个 locale 补上 nav_translations，该菜单标题就会保持蒙古语——构建并不会失败，因此只能靠肉眼发现。

从右至左的文字（RTL）¶

العربية 自右向左阅读。Material 能识别 ar locale，自动设置 <html dir="rtl">，并自行翻转菜单、标题与表格的排布——无需另行指定 direction。

不过，代码块与 ASCII 图在 RTL 下仍保持从左至右。这是正确的：技术性记法（URL、命令、YAML）一旦颠倒方向，含义就被破坏了。

西里尔字母标题的锚点¶

标准 slugify 会丢弃西里尔字母

Python-Markdown 的 toc 默认 slugify 会删除非 ASCII 字符。结果是 ## Танилт 这样的标题拿到一个空 id，页面内链接（#танилт）随之失效。

解决办法是使用保留 unicode 的 slugify：

markdown_extensions:
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}

本站也是这样配置的。

翻译的次序¶

新增文档时：

先用蒙古语写好原文——源头永远是蒙古语。
用 strict 构建把蒙古语版本稳定下来（会校验链接与锚点）。
然后一次性翻译成六种语言。只译一半会让各语言之间产生内容偏差。

把一页在所有语言上做完

按页推进优于按语言推进：把同一份文档同时译成六种语言，术语、结构、表格行都能保持一致。反过来「先把所有页面译成英文」，那么后译的语言就得去追赶一份已经变过的原文。

什么要译，什么不译¶

需要翻译	保持原样
正文、标题、表格内容	域名（`sso.gerege.mn`）
说明、警告、提示	仓库名（`template-gerege-mn`）
图示中的说明性标签	代码、YAML、命令、endpoint 路径
表头	产品名（eID Mongolia、G-Sign）
状态徽标文字	标准名称（OIDC、PKCE、RFC 3161）

文件名与目录结构永不翻译——是 platforms/sso.ru.md，而不是 платформы/sso.md。这样切换语言时 URL 路径保持一致，深层链接也能继续生效。

本站现状¶

生态系统层面文档的全部页面均已备齐七种语言：

Locale	语言	路径	状态
`mn`	Монгол （默认）	`/`	✅ 完整
`ar`	العربية	`/ar/`	✅ 完整
`zh`	中文	`/zh/`	✅ 完整
`en`	English	`/en/`	✅ 完整
`fr`	Français	`/fr/`	✅ 完整
`ru`	Русский	`/ru/`	✅ 完整
`es`	Español	`/es/`	✅ 完整

fallback_to_default 仍保持开启——当新增页面而翻译滞后时，该页会显示蒙古语原文，站点依旧完整。

若发现错误或表述别扭之处，欢迎向仓库提交 PR——详见本文档平台。