用 Codex 做多语言国际化(i18n)文案抽离与缺失 Key 自动扫描补齐实战

老项目满屏硬编码中文,手工抽离 i18n 文案又慢又容易漏 Key 或弄坏插值占位符?本文讲清如何用 Codex 搭配确定性 AST 扫描脚本,按模块安全抽离文案、对齐命名规范并自动检测补齐多语言缺失 Key。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-19 · 依据官方文档与公开资料整理 Plus 账号

结论先说

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

Codex 国际化文案抽离与缺失 Key 补齐五步流程

图:本站根据 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)。

i18n 文案抽离与翻译上线前六项质检清单

图:本站结合多语言前端上线实践整理的质检清单示意图

订阅与账号准备提示:出海项目一次性改造全站几十个路由模块,或同时维护英、日、韩、西多套语言包时,上下文与多轮校对会较快触及 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 团队定制方案。实时价格以商品页展示为准,售后执行掉订阅按剩余天数折退、封号不在质保范围规则。

相关教程

参考资料

  • 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/

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 整理家庭装修预算明细、隐蔽工程验收清单与主材优缺点对比表实战

    第一次装修面对几十页施工报价单、密密麻麻的水电防水隐蔽项目与五花八门的主材参数,极易踩坑增项。本文梳理用 ChatGPT 审查装修报价漏项、生成带公式的预算明细表、定制工地隐蔽工程验收单与主材对比表的实战提示词。

    ChatGPT0
  2. 02

    用 ChatGPT 做费曼学习法读书共读:反向追问检验自己是否真读懂专业书籍与整理书单笔记

    读完一本专业硬书常感觉「合上书就忘」,直接让 AI 概括全书又容易产生懂了的错觉。本文介绍用 ChatGPT 结合 Study Mode 与费曼学习法做反向追问共读,通过通俗复述、挑刺盲区到沉淀书单卡片的完整流程与提示词。

    ChatGPT0
  3. 03

    用 ChatGPT 做外贸产品多语种目录、展会邀约与客户跟进节奏表(附脱敏与本地化提示词)

    做外贸展会与海外推广时,手工翻译十几款产品目录费时且容易留下一堆中式英文,展后客户跟进也常缺节奏。本文梳理用 ChatGPT 先脱敏建术语库、再批量产出多语种目录、展前邀约函与展后 21 天跟进节奏表的实战流程与提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写高质量技术专栏文章、开源项目 Release Notes 与版本更新日志实战

    让 AI 直接凭空写技术文章容易满篇空洞套话,直接甩 Git 记录写更新日志又常常漏掉破坏性变更。本文整理用 ChatGPT 结合真实代码片段、压测数据与 PR 摘要,高效产出深度技术专栏、GitHub Release Notes 与 CHANGELOG 的实战工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做产品用户访谈纪要编码、提炼高频痛点需求池与 RICE 优先级打分实战

    手头攒了十几份用户访谈逐字稿,手工贴便利贴归纳痛点耗时又容易带入主观偏见。本文分享用 ChatGPT 完成脱敏检查、逐份开放式编码、跨样本聚类高频痛点并搭建 RICE 优先级打分表的 5 步实战流,附可直接复制的三段核心提示词。

    ChatGPT0
  6. 06

    ChatGPT 网页版上传超过 10 个文件或回形针附件按钮变灰怎么办:打包合并与配额限制排查

    在 ChatGPT 网页版批量分析文档时,常遇到一次选超 10 个文件被拦截或输入框回形针按钮变灰。本文依据 OpenAI 文件上传与存储说明,梳理 6 类常见报错的分流排查法,提供 ZIP 打包、本地合并与 Projects 复用方案及可直接复制的解包提示词。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~