进阶 nezha.wiki 2026-11-22 14:47:47 · 0 阅读
第5章 国际化与双语文档
国际化与双语文档 哪吒有三套独立的语言资源:Dashboard Go 文本、用户/管理前端 UI,以及文档站。修改其中一处不会自动翻译其它部分。通过 Weblate 参与 日常翻译优先通过 Nezha Hosted Weblate 提交,避免与自动同步产生重复改动。新增源文本或新语言时,仍需在对应仓库接入资源。Dashboard:gettext 资源位于 pkg/i18n/translations//LC_MESSAGES/nezha.po 与编译后的 nezha.mo;模板为 pkg/i18n/template.pot。使用已有 Localizer 的 T、Tf、ErrorT、N 等方法,不在处理器里直接拼接待翻译句子。在 Dashboard 根目录、Bash 4+ 与 gettext 工具可用时运行:bashbash script/i18n.sh generate template
bash script/i18n.sh update zh_CN
bash script/i18n.sh compile zh_CN顺序为提取源文本、合并 PO、完成翻译、编译 MO。最后两步之间应编辑/审查 PO。只改 PO 不会更新运行时嵌入的 MO,编译后还需重建 Dashboard。新增语种时核对实际资源目录及语言注册,不将某个前端的区域码格式直接搬进后端。Tf/ErrorT 的格式占位符必须与原文对应;复数词条沿用 N 的现有约定。不要翻译 JSON 字段、API 路径、scope、命令或程序读取的枚举值。用户与管理前端:i18next 两个前端都在各自 src/locales 下维护 JSON,但语言目录、注册和键不保证相同。用户前端入口为 src/i18n.js,管理前端为 src/lib/i18n.ts。新增键时同步基础语言与翻译,保持插值名、复数和嵌套结构。新增语言要导入资源、登记语言代码并检查切换器。不能只新增 JSON 文件就宣称支持。翻译验收包括长文本、按钮换行、日期/数字格式、缺失键回退、语言切换后的状态保留。不要为匹配中文宽度写死组件尺寸。主题贡献还需跑前端检查。文档站:成对维护 中文 docs//.md 对应英文 docs/en_US//.md。每次功能文档更新同时检查:标题、说明、默认值、边界条件和示例语义一致。英文内部链接指向 /en_US/ 对应页面,锚点在目标语言真实存在。导航修改在 docs/.vitepress/config.mts 两个语言区同步。页面有准确的 description;共享 SEO 逻辑生成 canonical、hreflang、站点地图和结构化数据。对重要入口同步 docs/public/llms.txt,不用隐藏的结构化文本宣传正文没有的能力。在文档根目录执行 npm test 和 git diff --check。机器检查验证结构,仍要人工核对权限、默认值和否定句,避免翻译把“不能”变成“可以”。