Mac版Codex国际化(i18n)技巧：多语言JSON批量提取翻译指南

先说几个关键判断：Mac版Codex本身确实不内置国际化功能，但通过命令行工具链和VSCode插件的组合，完全可以实现多语言JSON文件的自动提取与翻译。你不需要手动打开每个JSON文件复制粘贴，也不用在网页端反复切换语言选项。

Mac版Codex需借助json-autotranslate CLI与i18n-ally插件实现多语言JSON自动提取与翻译：先确认locales/下含规范源文件zh-CN.json，再通过jsontt scan识别缺失键、jsontt translate-dir批量补全（须加--preserve-structure），最后用i18n-ally在VSCode中实时校验与微调。

确认项目结构并准备源语言文件

打开终端，cd到项目根目录，确认存在locales/文件夹。这个目录下至少要有一个完整的源语言JSON文件——通常用zh-CN.json作为翻译基准。文件内容必须是纯键值对格式，比如：{ "login_button": "登录", "welcome_title": "欢迎使用" }。键名必须全小写、下划线或中划线分隔，不能含空格或中文标点。这一点很重要，因为如果存在嵌套对象、数组或注释，json-autotranslate会跳过整条键，导致漏译。

安装并配置json-autotranslate CLI

全局安装工具很简单，执行：

npm install -g json-autotranslate

装完跑一下jsontt --help，能显示帮助就说明成了一半。如果提示“command not found”，重启终端或者运行source ~/.zshrc刷新环境变量就行。整个过程不需要修改任何配置文件，所有参数都支持命令行即时传入。

批量提取未翻译键并生成目标语言文件

这一步分三步走，每一步都有明确的命令和参数。

第一步：扫描所有语言文件，识别缺失翻译的键

jsontt scan -s locales/zh-CN.json -d locales/

这个命令会读取locales/下所有JSON文件（比如en-US.json、ja-JP.json），和zh-CN.json做对比，然后列出所有缺失的key。结果直接显示在终端，不会动原来的文件。

第二步：一键补全缺失键（默认用Google Translate引擎）

jsontt translate-dir -s locales/zh-CN.json -d locales/ -t en-US,ja-JP,ko-KR --preserve-structure

务必加上--preserve-structure参数。否则嵌套路径会被扁平化，比如{"user": {"login": "登录"}}会变成{"user.login": "Login"}，导致前端调用$t('user.login')失效，破坏Vue或React i18n的命名空间结构。

第三步：如果要用DeepL提升商务术语准确度

先注册API密钥，然后导出环境变量：export DEEPL_AUTH_KEY="your-deepl-api-key"，接着指定引擎：jsontt translate-dir -s locales/zh-CN.json -d locales/ -t fr-FR --engine deepl

用i18n-ally在VSCode中实时校验与微调

打开VSCode，确保安装了i18n-ally扩展（Antfu出品）。工作区根目录存在locales/后，右键任意JSON文件 → “i18n: Sync All Locales”，系统会自动对齐所有语言文件的键结构。

编辑器右侧会出现翻译面板，在搜索框输入“login”，就能横向对比中/英/日三语对应值。发现某处翻译生硬时，直接双击英文字段修改，保存后会自动同步到磁盘。

这里有个提醒：手动修改后不要重新跑CLI翻译，否则你的手工优化会被覆盖。如果确实需要重新触发翻译，只对特定key加--force-keys login_button参数就行。