结论先说
- 做国际化改造不要让 Codex 凭肉眼全仓硬扫,正确分工是「确定性脚本负责清点差异,Codex 负责语义抽离与上下文翻译」。用脚本做 AST 扫描和 JSON 键集差集(零遗漏),让 Codex 依据组件语境起清晰语义 Key、替换代码并补齐自然译文。
- 动第一行组件代码前,先把 Key 命名规范、占位符格式与禁止触碰项写进
AGENTS.md。明确哪些字符串绝对不能抽离(如日志文案、埋点事件名、接口枚举值、正则表达式与 CSS 类名),防止模型把业务枚举值一起抽进翻译文件导致功能报错(护栏写法参考 /guides/codex-agents-md-guardrails-stop-deleting-tests)。 - 动态拼接句必须整体改写为命名插值或 ICU 复数语法,绝不按片段拆开翻译。例如把
"共 " + count + " 条结果"改写成单一带占位符的 Key(如"totalResults": "共 {{count}} 条结果"或 ICU 格式),否则切到英文、日文语序时会彻底拼成病句。 - 每次补齐缺失 Key 后必须跑自动校验脚本,强制断言所有语种「键集合一致 + 插值变量名一致 + 无空串」,避免译文把
{{userName}}误译成{{用户名}}引发运行时渲染异常。 - 跨数十个页面抽离文案并同步维护多套语种 JSON,连续几轮改动会消耗较多上下文额度。国内没有外币卡的开发者可在本站自助开通 ChatGPT Plus 充值 或无 5 小时限额的 ChatGPT Pro 充值,多人出海产品研发团队可咨询 ChatGPT Business 团队定制。

图:本站根据 i18next 与 FormatJS ICU 规范整理的流程示意图
本文根据 OpenAI Codex 官方文档《Codex CLI》《Non-interactive mode》、i18next 官方文档《Essentials》及 FormatJS 官方文档《ICU Syntax》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 需要给已有中文单语言 Web / 小程序 / 桌面应用补齐英文、日文等多语言支持,面对几百个组件硬编码文案无从下手的前端与全栈工程师;
- 项目已接入
react-i18next、vue-i18n或FormatJS,但每次发版总有新增文案忘记同步到其他语言 JSON、线上露出原始 Key 的团队; - 想把多语言 Key 命名规范、插值变量校验与缺失 Key 检查固化成自动化脚本的研发人员。
一、第一步:先立 AGENTS.md 规范,再让 Codex 写好确定性扫描脚本
先把国际化工程规范固化在仓库 AGENTS.md 中,避免不同批次抽出的 Key 风格打架:
markdown
## i18n 国际化改造护栏
- Key 命名统一使用 `模块.区域.语义` 小写驼峰格式(如 `order.detail.cancelConfirm`),严禁使用无意义流水号 `text_001`。
- 禁止抽离:console/logger 日志、分析埋点 event 名、后端接口状态枚举、API 路径、测试断言以外的常量键。
- 含变量的文案必须使用完整句子加命名占位符(如 `{{count}}` 或 `{count}`),严禁把一句话拆成前后两段拼接。
- 翻译到其他语种时,严禁修改或翻译 `{{var}}`、`<0>...</0>`、HTML 标签及 ICU 语法关键字。
紧接着,让 Codex 先写出一个确定性的本地检查脚本 scripts/check-i18n.mjs,用来完成三件机器最擅长的事:
- 扫描
src/中所有t('...')调用与基准语言包locales/zh-CN.json比对,找出「代码用了但基准包缺失的 Key」与「语言包里已废弃的僵尸 Key」; - 以
zh-CN.json为基准,对比en-US.json、ja-JP.json等目标语种,精准导出缺失 Key 清单 JSON; - 提取每条基准文案里的占位符变量集合(如
{{amount}}、{count}),断言目标语种包含完全相同的占位符名称。
二、第二步:按页面模块分批抽离硬编码文案
和重构老代码一样,绝不要一口气让 Codex 改 80 个组件。按业务目录(每次 3–6 个组件文件)推进,单批提示词示范如下:
text
请将 src/pages/billing/ 目录下的组件硬编码中文用户可见文案抽离到 i18n(项目使用 react-i18next,命名空间为 billing):
1. 严格遵循仓库 AGENTS.md 中的 i18n 护栏,跳过日志、枚举值与注释,不改动任何业务逻辑与样式类名;
2. 组件中引入 useTranslation('billing'),遇到含动态变量或标签高亮的句子,统一改写为完整带命名占位符或 Trans 组件的写法;
3. 同步写入 locales/zh-CN/billing.json,并为 locales/en-US/billing.json 补齐贴合 SaaS 账单语境的自然英文译文;
4. 完成后运行 `node scripts/check-i18n.mjs` 与类型检查,汇报新增 Key 数量、需人工核对的歧义文案及校验结果。
若改完后触发大量 TypeScript 类型提示或 ESLint 格式告警,可配合规则分组批处理一次收敛清零(详见 /guides/codex-batch-fix-typescript-eslint-ruff-errors)。

图:本站结合多语言前端上线实践整理的质检清单示意图
订阅与账号准备提示:出海项目一次性改造全站几十个路由模块,或同时维护英、日、韩、西多套语言包时,上下文与多轮校对会较快触及 Plus 配额上限(省额策略可看 /guides/codex-save-usage-quota-model-reasoning-context-tips)。集中攻坚期建议在站内升级 ChatGPT Pro 5x iOS 可覆盖档 或 ChatGPT Pro 5x 信用卡不可覆盖档;新账号首次开通 Codex 如在手机验证步骤受阻,可查看 Codex 注册手机验证服务。
三、第三步:日常迭代的「缺失 Key 自动扫描 + 增量补齐」闭环
老文案抽完后,更持久的价值是保证以后每次业务迭代不再出现「中文改了英文漏补」:
bash
# 1. 用确定性脚本导出所有目标语种缺失的 Key 与对应中文原文
node scripts/check-i18n.mjs --export-missing > missing-keys.json
# 2. 让 Codex 读取产品术语表(glossary.md)与缺失清单,仅增量补齐目标语言包
codex exec --ephemeral --sandbox workspace-write \
"请读取 docs/i18n-glossary.md 术语表与 missing-keys.json,将缺失的 Key 增量补齐到对应目标语言 JSON 文件中:
1. 严格沿用术语表里的产品专有名词译法,保持既有键排序和缩进格式;
2. 严禁修改已有译文与任何 {{...}} / {...} 占位符变量名;
3. 补齐后运行 `node scripts/check-i18n.mjs`,确认缺失数与占位符校验全部清零。"
提交 PR 前再跑一次 codex review --uncommitted 抽查是否存在把按钮文案翻得过长导致布局撑爆的风险(预审用法见 /guides/codex-review-base-uncommitted-custom-focus-guide),并把 node scripts/check-i18n.mjs 写进 CI 必过检查项。
常见问题
问:项目里有 t(status.${code}) 这种动态拼接 Key,静态脚本误报成「僵尸 Key」怎么处理?
答:建议尽量把动态 Key 改成显式常量映射表(例如 const STATUS_LABEL_KEY = { paid: 'order.status.paid', ... }),既方便 TypeScript 做 Key 存在性类型提示,也能让扫描脚本精准识别;确有少量无法消除的动态前缀,在检查脚本中加显式白名单注释即可。
问:怎么避免 Codex 在不同页面把同一个产品词(例如「工作区」「席位」)翻译出五花八门的英文?
答:在仓库里维护一份精简的 docs/i18n-glossary.md(列出 20–50 个核心业务名词的中英文对照与禁用译法),并在 AGENTS.md 中要求每次翻译必须先读取术语表,就能显著稳定全站用词一致性。
问:国内没有外币信用卡,或者公司研发团队需要统一采购开具增值税发票,怎么开通 ChatGPT / Codex 订阅?
答:可通过本站 AI 会员充值总览 按需选购 ChatGPT Plus 充值、ChatGPT Plus 自助卡密 或配额更高的 ChatGPT Pro 充值,支持支付宝、微信支付及 AlipayHK,提供卡密自助兑换(无需交出账号密码)与客服协助,并支持开具增值税发票;多人团队也可咨询 Business 团队定制方案。实时价格以商品页展示为准,售后执行掉订阅按剩余天数折退、封号不在质保范围规则。
相关教程
- 写好 Codex AGENTS.md 防护护栏:禁止乱删测试与敷衍绕过
- 用 Codex 批量修复 TypeScript / ESLint / Ruff 报错:按规则分组收敛指南
- Codex 本地 codex review 进阶用法:按 --base、--uncommitted 与自定审查重点
- Codex 省额度实战技巧:模型选择、推理强度与上下文控制
参考资料
- OpenAI Codex 官方文档:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
- OpenAI Codex 官方文档:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode
- i18next 官方文档:Essentials — https://www.i18next.com/translation-function/essentials
- FormatJS 官方文档:ICU Syntax — https://formatjs.io/docs/core-concepts/icu-syntax/
0 条评论
还没有评论,来抢沙发~