本地化目录生命周期

ZeroClaw 有两个本地化分支，格式和使用方各不相同。Mozilla Fluent 目录为运行时和 zerocode 提供应用程序字符串。gettext 目录在英文源文件和生成的参考资料完成汇编后，翻译 mdBook 文档。

这些分支共享同一个语言区域注册表和基于提供程序的填充理念，但它们并不能互换。仓库中跟踪的某个已翻译文件也不能证明特定二进制文件会嵌入或加载它。请使用本页面来跟踪每个目录，从英文源开始，经过生成、验证、运行时或站点消费，直至发布。

两个本地化分支

locales.toml 是语言区域代码与显示标签的共享注册表。它驱动文档的多语言构建和生成的语言切换器，并由运行时嵌入以实现语言区域发现。它本身并不会使每个目录对每个使用者都可用；每个加载器仍需自行定义其文件的嵌入方式或磁盘查找路径。

Fluent 应用程序字符串

英文 Fluent 文件是由作者编写的源文件。键用于标识消息，值则包含英文文本和任何 Fluent 变量。根据消息契约的要求，产品名称、命令字面量、标识符和占位符保持原样。

cargo fluent 遍历运行时和 zerocode 目录根节点。fill 将每个英文文件与所选语言环境进行比较，通过已配置的模型提供商翻译缺失的键，在每批次处理后写入进度，并修改已跟踪的 .ftl 文件。check 解析目录语法，scan 比较源引用与目录，stats 在不修改目录的情况下报告覆盖率。Fluent 差异应属于专项本地化变更，而非附带的应用工作。

存储和加载是相互独立的关注点：

• 运行时 CLI 字符串始终包含内嵌的英文。加载器还可以使用由 builtin_cli_ftl_source 内嵌的已翻译 CLI 目录，然后将磁盘目录应用为优先级最高的本地化来源。
• 运行时面向提示的工具描述始终内嵌英文，并叠加来自磁盘的已翻译 tools.ftl 值；可选的缺失查找不返回任何值。
• zeroclaw-tools 独立内置英文，并从磁盘加载 tools.ftl，用于工具自有的架构和结果字符串，因为其 crate 无法依赖 runtime；必需查找项缺失时，会呈现为可见的 {key} 标记。
• zerocode 内嵌其英语目录，并从磁盘覆盖已翻译的 zerocode.ftl。ZEROCODE_LOCALE_DIR 是显式测试覆盖项；常规共享位置为 <config-dir>/data/ftl/<locale>/zerocode.ftl。
• zeroclaw locales fetch 会使用 zeroclaw-config 声明的 catalog 路径，将所选的运行时和 zerocode catalog 下载到该共享磁盘 locale 目录中。

对于运行时、工具和 zerocode，英语仍是基础映射。磁盘上的翻译目录或内置目录会替换其包含的键；缺失的翻译键则保留其英文值。必需的查找会报告一个在所有可用来源中都不存在的键，并显示一个可见的 {key} 标记，而不是静默生成文本；可选的运行时工具描述查找则不返回任何值。

gettext 文档字符串

英文 Markdown 是编写文档的源文件，但提取过程还会看到为提取构建物化的生成参考、包含的片段以及预处理器输出。在运行带有 xgettext 输出的 mdBook 之前，cargo mdbook sync 会调用由语言区域构建和单语言区域服务共用的 prepare_generated_book_inputs() 路径。该路径会从其权威来源重新生成 CLI 和配置参考、语言区域切换器、主题、键位映射、硬件、feature-matrix 以及插件输入。提取还会使用已构建的 peer-groups 预处理器运行，因此干净的检出不依赖被忽略的文件或早期文档构建留下的二进制文件。

cargo mdbook sync 会将英文消息提取到 messages.pot，规范化模板，在不进行模糊匹配的情况下引导或合并各个语言环境，移除过时的条目，并报告未翻译的差异。当提供了模型服务商时，它会通过 tools/fill-translations 填充缺失的翻译；否则不会发起任何服务商调用。维护者指南负责说明该命令的选项和操作流程。

fill 工具将每个 gettext 条目视为一次从源文本到译文的映射。它会修复或清除包含提示词泄漏或新的机器本地绝对路径的模型响应，保留必需的尾随换行符，进行增量写入，并从已接受的条目中移除 fuzzy 标记。cargo mdbook check 会单独解析每个 PO 文件，并拒绝可疑的生成响应、损坏的受保护字面量以及引入的本地路径。

部分翻译和回退

当某个 locale 对该条目没有可用的翻译值时，gettext 预处理器会渲染英文 msgid。因此，一个 locale 可能会在已翻译的导航和段落旁显示新添加的英文正文。这种混合语言状态意味着英文源内容已超出目录已接受的覆盖范围；并不意味着 mdBook 为同一页面选择了两种语言。

常见原因包括：

• 英文文档或生成的参考文档变更新增了一个 msgid；
• 目录同步已合并新源，但尚未运行翻译填充；
• 安全修复屏蔽了泄露的、含路径的或其他不可用的模型响应；
• 源代码编辑将旧消息替换为新消息；
• 区域设置目录或发布固定项有意落后于当前 master。

Fuzzy 是一种目录维护状态，而非旧值可安全渲染的保证。当前 sync 命令会为新合并禁用模糊匹配，而 fill 工具可接受现有的非空模糊值并移除其标志。请审查生成的 msgstr；切勿仅凭该标志推断发布行为。

翻译后的语言环境构建会禁用全文搜索。只有主语言环境（即 locales.toml 中的第一个条目）会生成搜索索引。这是 build_locales 中出于大小考量所做的决定，而非翻译覆盖率不足所致。

目录存储和发布版本固定

Fluent 目录位于主仓库中。常规的 Fluent 翻译改动会直接更新目标 .ftl 文件，并与使用这些键的应用代码一起审查，或作为专门的翻译处理进行审查。

文档 PO 消息目录位于 zeroclaw-labs/zeroclaw-docs-translations，并作为 git 子模块挂载在 docs/book/po。主仓库记录的是一个 gitlink 提交，而不是每个 PO 文件。messages.pot 和翻译失败日志是生成产物，不属于固定的消息目录集。

发布辅助脚本 scripts/release/refresh-translations.sh 负责翻译标签和主仓库 gitlink 的更新。默认情况下，它会运行同步和目录检查，在子模块中提交并推送目录变更，创建并检出匹配的 v<version> 标签，然后暂存 gitlink。其 --no-translate 模式会跳过同步和目录检查，因此仅适用于当前目录已单独验证之后的情况。翻译固定工作流会初始化确切的固定提交、检查 PO 语法，并验证各语言环境目录暴露相同的 msgid 集合。

文档部署会初始化锁定版本的子模块，并构建所有已有的语言区域。它不会调用模型提供商、补全缺失的翻译、更新子模块，也不会创建发布标签。

验证和审查边界

• 普通的英文文档 PR 可以将大范围的 PO 变更推迟到一次专门的翻译缓存处理中完成。请在原始 PR 中审查英文源文件和生成的边界。
• 当翻译或目录维护是目的、正在添加语言区域、生成的差异较小且可审查，或发布流程正在推进版本锁定时，请包含 PO 更改。
• 当键或已翻译的应用字符串发生变更时，应一并包含 Fluent 的变更。不要仅因某个 .ftl 文件存在，就断言对应的已翻译运行时路径可用；请验证相关的加载器或 fetch/install 路径。
• 保持受保护的命令语法、配置键、产品名称、JSON/TOML 字面量和占位符不变。翻译周围的说明文字，而不要削弱面向机器的示例。
• 将英文回退内容视为已接受的目录覆盖缺失的明显证据。应修复或补全目录源文件，而非渲染后的 HTML。
• 将子模块变更作为发布/目录操作进行审查：检查主仓库的 gitlink 以及它所选定的目录提交。

有关详细命令、提供商配置、批处理、添加语言区域以及发布流程，请参阅 文档与翻译。有关为 gettext 提取提供源文本的英文源文件阶段和生成参考阶段，请参阅 生成文档管道。

源指针

• 区域设置注册表：locales.toml
• 运行时 Fluent 加载器：crates/zeroclaw-runtime/src/i18n.rs
• 工具自有的 Fluent 加载器：crates/zeroclaw-tools/src/i18n.rs
• 运行时 Fluent 目录：crates/zeroclaw-runtime/locales/
• zerocode Fluent 加载器：apps/zerocode/src/i18n.rs
• zerocode Fluent 目录：apps/zerocode/locales/
• 流畅工具链：xtask/src/cmd/fluent/
• 目录下载映射：zeroclaw_config::schema::FTL_CATALOGS
• gettext 提取与合并：xtask/src/cmd/mdbook/sync.rs
• gettext 安全检查：xtask/src/cmd/mdbook/check.rs
• tools/fill-translations/
• 区域设置的构建和搜索行为：xtask/src/cmd/mdbook/build.rs
• 翻译固定版本验证：.github/workflows/validate-translations-pin.yml
• 发布目录刷新：scripts/release/refresh-translations.sh
• 文档部署：.github/workflows/docs-deploy.yml