OneTHU 翻译交接指南¶
0.11 工程以当前 dev3 为准，业务源文与提取位置由交接工具生成，不回填旧分支的业务文件。本目录已生成可用词典、上下文清单和批次。翻译任务只填写目标词典的字符串值。
文件与工作边界¶
| 文件 | 用途 | 翻译者是否修改 |
|---|---|---|
apps/desktop/src/i18n/locales/zh-CN.ts |
中文事实源 | 否 |
apps/desktop/src/i18n/locales/en-US.ts |
英文译文，空字符串表示待译 | 仅本批 messages 值 |
docs/i18n/catalog.json |
完整源文、当前调用位置、参数及源文版本 | 否 |
docs/i18n/batches/001.json 等 |
每批最多 80 条、目标文件、已有译文和用途 | 否 |
docs/i18n/GLOSSARY.md |
术语和容易误译的动作区别 | 否 |
tools/i18n*、组件、状态、请求和解析代码 |
工程实现与验证 | 否 |
pending 表示未填；prefilled-review 表示已有候选译文，仍须按上下文复核。已有译文来自运行时、OneGUI 或与当前中文完整匹配的旧译文；这不代表已经完成语言质量验收。不要用“文件有全部键”当作翻译完成。
每个批次的 sourceHash 对整个中文词典生效。源文变更后旧批次会被拒绝，工程负责人应重新生成。不要手动修改 hash 或批次清单。键中末尾的摘要用于稳定定位，不是给翻译者解读的产品术语。
开始与验收¶
工程负责人先提交工程基线，给翻译者一个干净的检出目录。多个模型不要同时写同一词典。先做一批校准质量，再依次推进；每批通过后提交，再以该提交作为下一批基线。翻译者无需运行提取脚本，也不应修改业务代码。
在开始修改前记录工程基线：
ONETHU_TRANSLATION_BASE=$(git rev-parse HEAD)
仅修改该批允许的英文字符串，随后在仓库根目录执行：
node tools/i18n-test.mjs \
--locale en-US \
--batch docs/i18n/batches/001.json \
--base "$ONETHU_TRANSLATION_BASE"
这条命令检查词典语法、重复/缺少/未知键、占位符集合与次数、批次源文版本、本批非空、越批改值、修改中文/业务/测试等其他文件，以及改动导入、键和词典结构。只准改字符串值，避免重新格式化整份文件。失败时修复译文，不修改检查器。
全量工程检查允许其他批次暂时为空：
pnpm i18n:check
英文准备发布时必须通过全覆盖检查：
node tools/i18n-test.mjs --locale en-US --complete
目前英文存在大量空值，因此全覆盖检查应当失败。运行时回退中文保证可用，不能以这个回退替代翻译。
新增语言由工程负责人预置与中文相同键集的纯数据文件（如 fr-FR.ts）；Vite 自动注册，三种模式的语言选择器无需改业务代码。不要让翻译模型自行修改运行时、类型或注册表。Node 单元测试有内建语言种子，新增语言还须跑真实 Vite 注册及浏览器验收。
文案格式¶
只使用已经存在的 {name} 具名占位符，可以调整顺序，但名称、大小写和出现次数必须一致。
源文：同步失败：{reason}
译文：Sync failed: {reason}
源文：第 {week} 教学周
译文：Week {week}
运行时不会解释 ICU、HTML、JSX 或 Markdown。不要写 {count, plural, ...}、<a> 或自行加入链接。富文本槽位也是 {name}，由工程传入真正的按钮、链接或强调节点，译文只调整它在句子中的位置。示例中的 LaTeX、JSON 等有意义的花括号由参数传入，不要把公式改成新的占位符。
复杂消息的 parameters 和 locations.context 说明参数来源。自动生成的 value、value2 必须结合表达式阅读；它们仍是稳定参数名，不要擅自改名。没有参数的句子不要新增占位符。原有复数分支由工程定义，翻译者只翻已有分支；本轮不要求模型发明新的消息语法。
native.widget.* 是 Android 桌面小组件的 62 条模板，也只在目标词典填写。带 .zero/.one/.two/.few/.many/.other 的条目按目标语言的数量规则分别翻译；{count} 保留。应用会把当前语言和这些模板传给原生小组件，后台刷新继续使用同一语言。不要修改 Kotlin 或生成的中文兜底资源。
按钮尽量短，完整说明保留权限限制、数据范围与失败后果。不要为了缩短文案删去“仅本机”“尚未同步”“需要负责人权限”等含义。保留原有换行；不能把一段危险操作说明压缩成含义模糊的“确定吗”。
不翻译的内容¶
- 学生/老师姓名、课程、作业、新闻、邮件、文件、用户组织及自定义标题，保持原文。
- 稳定 route/tab/section ID、学校状态判定、API 字段、路径、权限值、CSS、代码和系统日历身份不翻。
- 学校接口返回的错误详情可以作为
{reason}原样显示。翻译模型不修改解析器去“消灭中文”。 - OneTHU、OH、OneGUI、OneGO!、OnePage、OneShot、MCP、GitLab、THUBook 等品牌或协议名保持。
- 已有导览里的真实应用演示图和系统窗口不是词典内容；需要新的语言截图时由工程从真实界面重新捕获。
- 已发布的日历/通知、IM 自动回复、远端资料库名称等外部产物有自己的语言与身份边界，不因切换界面语言批量重写。
网络学堂课程显示在中文语言下用原课程名，其他语言优先学校提供的 englishName，缺失时保留原名；搜索同时识别两种名称。课程 ID、收藏与暂存对象身份保持原值。官方英文网页仅作为解析兼容依据，应用不会替用户修改学校网站的语言偏好；第三语言也不能把学校原文臆译成课程官方名称。
给翻译模型的任务模板¶
在干净的工程基线上翻译 OneTHU，目标语言为
en-US，本批清单为docs/i18n/batches/001.json。先阅读本指南、术语表和该批上下文。只修改apps/desktop/src/i18n/locales/en-US.ts中本批列出的messages字符串值；其他文件、键、导入、导出、label 和格式不变。逐条翻译完整表达，保留所有占位符及其次数。复核已有候选译文。按钮简洁，权限和危险操作说明完整；不翻用户、学校内容或品牌，不加入 ICU、HTML、JSX 或代码。
开始前记录
ONETHU_TRANSLATION_BASE，结束执行本指南的批次检查。若上下文无法支持准确翻译，报告具体 key 和疑问，不改业务代码或校验器。最后只报告完成键数、检查结果及待确认项，不宣称全站翻译完成。
工程维护¶
pnpm i18n:handoff 根据提取记录、显式种子、OneGUI 字典和当前调用生成词典及批次，保留中文源文未变的已有译文。中文变更的旧译文不自动沿用。该命令由工程维护者运行。
交接生成会同步 Android 的中文历史快照兜底资源；工程检查会核对它与中文词典一致。英文和新增语言由运行时快照传递，不需要维护第二份原生译文。
extract-current.mjs、merge-messages.mjs、fix-static.mjs 是本轮迁移辅助工具，不是翻译步骤。学校协议和持久化身份需要人工审查；禁止为了使中文扫描归零而全量重新提取。