文档目前只有中文。

国际化

1. 原则

1. Heartwood 不包含任何面向用户的自然语言。错误、任务标题、阶段名都是 {kind, args}。
2. 默认语言跟随系统区域，找不到精确匹配则按 BCP 47 回退（zh-Hant-TW → zh-Hant → en），最终回退英文。
3. 英文是源语言，所有键先有英文。
4. 翻译是数据，不进代码评审的逻辑部分，可以由社区在翻译平台上完成。

2. 源文件

bark/i18n/
├── en.json          源语言，键的唯一定义处
├── zh-Hans.json
├── zh-Hant.json
├── ja.json
└── ...

格式：扁平键值，键用点分命名空间，值用 ICU MessageFormat，支持复数与选择。

{
  "error.DOWNLOAD_HASH_MISMATCH": "The downloaded file is corrupted. Expected hash {expected}, got {actual}.",
  "task.stage.DOWNLOADING_LIBRARIES": "Downloading {count, plural, one {# library} other {# libraries}}…",
  "instance.playtime": "Played {hours, plural, one {# hour} other {# hours}}"
}

3. 生成到各平台

构建脚本 bark/i18n/build.py 把源 JSON 转为：

• macOS：Localizable.xcstrings（String Catalog）
• Windows：Resources/<locale>/Resources.resw
• Linux：gettext .po（后期）

生成文件提交进仓库，CI 校验与源一致。

4. 键的约定

• 错误：error.<KIND>，与 grain/schema/errors.json 一一对应，CI 检查每个 kind 都有英文翻译。
• 任务阶段：task.stage.<KIND>。
• 界面文案：<screen>.<element>，例如 instances.emptyState.title。
• 不复用键表达不同语义，哪怕英文相同。

5. 区域相关格式

日期、时间、文件大小、数字全部用平台原生格式化 API（Foundation、.NET Globalization），不在翻译文件里拼。