Roo Code 国际化实战指南使用 /roo-translate 命令完成扩展与 WebView 的多语言本地化【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code/roo-translate是 Roo Code 仓库内置的斜杠命令用于驱动 AI Agent 执行扩展的翻译与本地化任务覆盖核心扩展后端与 WebView 前端 UI 两大区域的 17 种非英语语言。本文将以该命令的定义文档.roo/commands/roo-translate.md为骨架结合仓库中的翻译规则.roo/rules-translate/001-general-rules.md、翻译技能.roo/skills/roo-translation/SKILL.md与缺失翻译校验脚本scripts/find-missing-translations.js的实现带你掌握从定位待译字符串、遵守翻译规范、批量更新语言文件到自动化校验的完整工作流。命令概览激活翻译工作流/roo-translate命令以 YAML frontmatter 声明其元信息--- description: Translate and localize strings in the Roo Code extension argument-hint: [language-code or all] [string-key or file-path] mode: translate ---description说明该命令的用途——翻译与本地化 Roo Code 扩展中的字符串。argument-hint定义了两个可选位置参数分别是语言代码或all与字符串键或文件路径。mode指定命令在translate模式下执行激活包含完整 i18n 准则的翻译工作流。命令本身是一份执行蓝图它不提供译文而是告诉 Agent 如何界定翻译范围、遵循哪些语言规范、用何种工具修改文件以及如何校验结果。快速开始界定翻译范围执行/roo-translate时第一步是根据参数确定本次任务的作用域指定语言代码例如de、zh-CN则只聚焦该语言的翻译。指定all对所有受支持语言进行翻译。指定字符串键定位并翻译某条具体字符串如welcome.title。指定文件路径直接针对某个翻译文件作业。支持的语言命令定义了完整的受支持语言列表ca, de, en, es, fr, hi, id, it, ja, ko, nl, pl, pt-BR, ru, tr, vi, zh-CN, zh-TW含英语共 18 种。这与仓库中 src/i18n/locales/ 与 webview-ui/src/i18n/locales/ 下的语言目录一一对应例如zh-CN/、ja/、pt-BR/等。其中pt-BR、zh-CN、zh-TW等包含区域后缀的代码需要精确匹配不能简写。翻译位置两大区域Roo Code 的本地化字符串分布在两个独立的目录翻译时需分清目标区域区域路径说明核心扩展Core Extensionsrc/i18n/locales/扩展后端逻辑中的用户可见字符串WebView UIwebview-ui/src/i18n/locales/React 前端界面的用户界面字符串两个区域使用的命名空间文件也不同。以英语基准目录为例核心扩展包含common.json、embeddings.json、mcp.json、skills.json、tools.json、worktrees.json六个命名空间WebView UI 则包含chat.json、common.json、history.json、mcp.json、prompts.json、settings.json、welcome.json、worktrees.json八个命名空间。此外VSCode 扩展的 manifest 级字符串如命令名、菜单项位于 src/package.nls.json 及对应的package.nls.locale.json文件如package.nls.zh-CN.json。翻译工作流从新增到校验命令文档给出了标准化的执行流程翻译规则文档.roo/rules-translate/001-general-rules.md中的 Workflow 部分对其进行了细化。新增字符串先添加英文原文所有新增字符串必须先写入英语语言文件en目录因为en是整个 i18n 体系中的基准与回退语言fallback。确认后再翻译添加英文后应先请求用户确认再向其他语言传播避免在英文文案尚未敲定时就产生大量重复劳动。高效编辑对已存在的文件使用apply_diff而非write_to_file后者整文件重写既慢又容易破坏 JSON 结构。更新已有字符串先识别所有受影响的语言文件先更新英文再向其他语言传播变更修改插值变量时务必谨慎——{{variable}}必须与英文源保持完全一致否则会破坏代码集成并引发语法错误。校验变更每次翻译完成后都必须运行缺失翻译校验脚本node scripts/find-missing-translations.js该脚本会对比所有非英语语言文件与英语基准文件报告缺失的键并生成报告。脚本还支持细粒度的筛选参数详见下文「自动化校验」小节。关键翻译准则命令文档与规则文档共同确立了以下硬性规范任何语言的文件都必须遵守使用非正式语气所有语言一律采用非正式称呼例如德语用du而非Sie。禁止在正式/非正式之间摇摆。保留技术术语不译token、Prompt等词在目标语言中已被广泛使用必须保留英文原词。原样保留占位符{{variable}}形式的插值占位符必须在所有语言中逐字符一致。保持用户视角若原文是用户对软件发出的指令译文必须保持这一方向不能变成系统对用户的命令。语境化翻译同一字符串在不同场景下含义不同时采用语境感知的翻译避免逐字直译追求文化贴切、自然流畅的母语表达。区分 UI 元素类型按钮标签使用简短祈使句如Save、Cancel工具提示文本可以稍长、更具描述性。不添加defaultValue英语翻译即回退值翻译文件中不应包含defaultValue字段。哪些字符串不需要国际化核心扩展并非所有字符串都需要翻译。规则文档明确指出仅用户可见的消息需要 i18n内部错误消息、调试日志、面向开发者的消息保持英文。例如formatResponse.ts中的部分字符串就刻意未国际化。因此翻译任务开始前应先判断目标字符串是否属于用户界面可见范围避免为内部日志做无谓的翻译。源码级原理i18n 的底层实现要正确翻译还需理解字符串是如何被取用的。核心扩展的翻译入口在 src/i18n/index.tsexport function t(key: string, options?: Recordstring, any): string { return i18next.t(key, options) }t()函数直接委托给 i18next 实例键可以携带命名空间前缀例如规则文档中提到的core:errors.missingToolParameter。在当前仓库中命名空间即src/i18n/locales/下的 JSON 文件名例如 src/i18n/locales/en/common.json 中嵌套定义了errors、confirmation等分组键。翻译时必须保证所有语言文件中这些嵌套结构的位置完全对齐。初始化逻辑在 src/i18n/setup.ts它扫描i18n/locales下的所有语言目录与 JSON 文件动态构建resources对象并以lng: en、fallbackLng: en初始化 i18next同时关闭escapeValue。这意味着英语文件既是默认语言也是缺失翻译时的回退兜底——这正是校验脚本以en为基准的原因。WebView UI 侧则采用 React 生态的react-i18next。webview-ui/src/i18n/TranslationContext.tsx 中的TranslationProvider在挂载时调用loadTranslations()加载全部语言并通过useTranslation()监听扩展状态中的language变化动态调用i18n.changeLanguage()切换界面语言useAppTranslationHook 则向组件暴露t函数。含内嵌组件的文本使用 TransWebView 中若文本内嵌了组件如链接、按钮必须使用 i18next 的Trans组件配合命名组件。翻译规则文档给出了完整示例。翻译字符串JSONchangeSettings: You can always change this at the bottom of the settingsLinksettings/settingsLinkReact 组件用法TSXTrans i18nKeywelcome:telemetry.changeSettings components{{ settingsLink: VSCodeLink href# onClick{handleOpenSettings} / }} /settingsLink尖括号标签在 JSON 中是内嵌组件占位符在components属性中映射到真实组件。翻译其他语言时尖括号标签本身必须原样保留只翻译标签之间的可见文本。自动化校验find-missing-translations.jsscripts/find-missing-translations.js 是翻译质量保障的核心工具其注释头部完整记录了用法node scripts/find-missing-translations.js [options]支持的选项选项说明--localelocale只检查指定语言如--localefr--filefile只检查指定文件如--filechat.json--areaarea只检查指定区域core、webview、package-nls或all默认--help显示帮助信息其中三个区域的定义为core后端对应 src/i18n/localeswebview前端 UI对应 webview-ui/src/i18n/localespackage-nlsVSCode 的package.nls.*.json文件src/ 下这些文件必须是扁平 JSON 结构脚本会对嵌套对象直接报错退出。从实现看脚本递归提取英语文件的全部点分路径键如errors.missingToolParameter逐个与各语言文件比对键缺失会列出键名与英文原文整个文件缺失会标记 File is missing entirely。报告以 ✅ / 表情分级输出若任何区域存在缺失脚本最终会以退出码 1 结束——这意味着它可以直接接入 CI阻止携带缺译的构建合并。规则文档要求发现缺失后补充翻译然后再次运行脚本直至所有区域通过。实战示例命令文档给出了三种典型调用/roo-translate de仅聚焦德语翻译——Agent 将只检查并处理de语言目录。/roo-translate all welcome.title将welcome.title这条字符串翻译到所有受支持语言。此时 Agent 会先在en中定位该键再用search_files找到各语言文件中的临近键作为apply_diff的 SEARCH 上下文批量补齐。/roo-translate zh-CN src/i18n/locales/zh-CN/core.json针对简体中文的指定翻译文件作业——Agent 会读取该文件上下文检查缺失键或修正既有译文而不触碰其他语言文件。翻译工作流中的工具策略规则文档对 Agent 的执行方式给出了明确约束这也是命令文档「使用apply_diff」要求的细化先在代码库中定位字符串出现的 UI/代码位置理解其语境与用途先更新英文翻译用search_files找出英文文件中靠近新键的既有键作为其他语言文件中apply_diff的 SEARCH 上下文不必逐个读取每个语言文件基于搜索结果用apply_diff为所有语言创建译文不要把译文输出到聊天窗口直接修改文件运行缺失翻译脚本校验。使用apply_diff时必须精确定位 JSON 中要编辑的结构避免语法错误编辑前应检查字符串在代码库中的使用位置确认修改不会破坏功能。常见陷阱与翻译自检清单规则文档专门列出了翻译者必须避开的常见错误在正式与非正式称呼间摇摆——始终保持非正式du而非Sie翻译或改动应保留英文的技术术语与品牌名修改或删除{{variable}}占位符——必须与英文源逐字符一致翻译在目标语言中已习惯使用英文的领域术语改变指令或错误消息的含义或细微差别忽视跨语言术语的一致性。每次翻译完成后对照清单逐项自检✓ 全程使用非正式语气du而非Sie✓ 所有占位符与英文源完全一致✓ 与既有翻译保持术语一致✓ 技术术语与品牌名在合适处保持英文✓ 保留原文视角用户→系统 vs 系统→用户✓ 针对 UI 语境按钮 vs 工具提示适配文本✓ 运行缺失翻译脚本确认校验通过。小结/roo-translate命令把「翻译 Roo Code」这件多语言、多区域、高重复度的工作封装成一条可复现的 Agent 工作流以en为唯一事实来源向 17 种语言传播用apply_diff增量编辑、用find-missing-translations.js把关质量。配合 .roo/rules-translate/001-general-rules.md 的语言规范与 .roo/skills/roo-translation/SKILL.md 的完整技能说明任何人都能驱动 Agent 高效、合规地完成从新增英文文案到全语言同步的本地化闭环。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考