SuperAPI AI 工具集

docs-localization-strategy

写作与研究

查看项目

更新于 10-23 10:26

技能介绍

用途 该技能充当文档本地化策略顾问,帮助团队针对每个候选语言(及变体,如 pt-BR 与 pt-PT、zh-Hans 与 zh-Hant、es-ES 与 es-419)给出是否本地化、本地化哪些页面、由谁负责、如何维护的决策。其核心主张是:决策单位应是一个语言变体、一组页面、一位具名负责人和一条退出规则,而不是笼统的“我们应该做本地化”。

主要能力

  1. 证据检验:在提出任何语言前,按顺序检验浏览器语言占比与国家占比、参与度差距(如快速上手完成率,基线为差距小于约 5 个百分点说明无明显理解障碍,大于约 10 个百分点说明存在)、需求语言(工单、论坛、社区聊天、搜索词)、已有替代手段(浏览器翻译、AI 助手、搜索引擎机翻)与商业权重。据此把候选语言分类为“障碍已确认且有负责人”“有需求但无负责人”“未显示障碍”,并给出启动、仅做源文档加固或拒绝的决定及解锁条件。
  2. 方案阶梯:按效率排序列出不做、源文档加固、关键路径包、LLM 审核集、持续标注机器翻译、社区项目、全量人工同步六种以上做法,分别说明投入、产出与长期负担,并从效率、价值、投入、持久性四个维度比较。默认建议为所有语言先做源文档加固,对通过检验且有负责人的语言加一个关键路径包。
  3. 页面选择:从审核人力反推页面规模,给出稳态与上线负载两项计算;首批覆盖快速上手、安装、认证、高流量任务页与站点 UI 字符串;第二层为核心概念页;生成的 API 参考只翻高流量页或不翻; identifiers、CLI 标志、HTTP 头、配置键、产品名、贡献者文档与文档站更新日志不翻译;代码保持可运行,仅按样例政策翻译注释与可读示例字符串;标题锚点保留源语言。
  4. 翻译与审核模型:机器或 LLM 翻译前遮蔽代码块,逐页校验代码围栏数、链接数与标题数;按风险分级审核(安全、认证、计费、配额、弃用、参数语义须发布前人工审核,其余页面达到浏览量阈值后审核);每页标注翻译方式并声明源页面为准,提供一键跳转与问题反馈;语言切换器记住读者选择,不按浏览器语言自动跳转。
  5. 新鲜度契约:每个译文页面绑定其源修订号,按源历史而非文件日期检测漂移;提供 scripts/translation-drift-check.py 在 CI 中运行,命令为 python3 scripts/translation-drift-check.py --source docs/en --locale ja=docs/ja --format csv,新语言可加 --fail-on no-pin,unknown-pin,已有语言可加 --since <ref>;页面状态包括 current、behind、far、moved、no-pin、unknown-pin、untranslated、orphan;脚本需 Python 3.8+ 与 git,只读。使用 gettext PO 或翻译管理系统时以 fuzzy 与未翻译计数衡量新鲜度;被引用的片段或生成区块变更也计为变化;落后页面显示横幅并链接源页;未翻译页与严重落后的关键路径页回退到源语言;按书面阈值退役页面与语言并重定向。

使用方式 以访谈形式逐题收集触发原因、候选语言与数据、产品自身本地化程度、文档规模与变更速度、托管工具链、负责人与投入上限、期限等;用户已答的问题跳过并复述。无持久记忆时,将选定语言、负责人、页面集、pin 字段名、阈值与退出规则写入计划的“Stored context”块。随后依次执行:检验源语言是否为障碍、头脑风暴方案并让用户选择、确定页面集、设定翻译与审核模型、编写新鲜度契约。

适用场景与限制 适用于开发者文档、开源项目文档与面向多市场的产品文档的本地化规划,尤其适合需要向管理层说明“为何暂不翻译某语言”或“翻译到什么程度”的团队。限制与前提:无负责人则除源文档加固外不启动任何语言;源文档高变更加低投入上限时只保留关键路径包;合同或法规点名语言时优先全量人工翻译指定范围;季度内的期限排除社区项目;多版本文档只翻最新版。该技能是策略与流程框架,不提供具体翻译引擎、价格或平台选型;文中引用的调查数据与项目先例均为外部资料,使用时需按团队实际数据替换基线值;脚本仅适用于镜像文件树,PO/TMS 场景以工具自身计数为准。