i18n-replace-react

i18n-replace-react 是一组命令行工具，帮助在 Next.js（App Router）项目中：

• 自动扫描并提取源码中的中文文本；
• 将中文映射为语义化的 i18n keys；
• 按映射替换源码中的 t(...) 调用以及 zh 目录下的 messages 文件；
• 生成国际化需要的json文件；
• 导出用于翻译的 Excel 文件（translations.xlsx）。

这些脚本会直接修改源码文件，使用前请务必对项目做 git 提交备份。

安装

npm install i18n-replace-react
# 或（开发依赖）
pnpm add -D i18n-replace-react

快速开始

• 查看可用命令：

npx i18n-replace-react

• 运行所有步骤（按固定顺序执行）：

npx i18n-replace-react all

CLI 命令与说明

• i18n-replace-react app — 扫描 app/[locale]/**/* 与相关 _components，提取中文并写回源码。
• i18n-replace-react components — 只处理 components/ 目录。
• i18n-replace-react translate — 将 zh 目录中提取到的中文翻译为英文 key（调用 DeepSeek API）。
• i18n-replace-react replace-message-keys — 按 keys-map.json 替换 zh 目录下 messages 文件的 key。
• i18n-replace-react replace-key — 在源码中按 keys-map.json 替换 t() 调用的随机 key 为最终 key。
• i18n-replace-react convert-excel — 导出 translations.xlsx（便于交付给翻译）。

示例：只运行提取页面与组件中的中文

npx i18n-replace-react app

注意：translate.js 中实现会把生成的 keys-map.json 写到 zh 目录的上一级（通常为项目根）。

示例工作流程

1. 提取页面与组件中的中文：

npx i18n-replace-react app

2. 将提取的 zh JSON 翻译为英文 key（需要 API Key）：

DEEPSEEK_API_KEY=sk-xxx npx i18n-replace-react translate

3. 按 keys-map.json 替换源码中 t() 的随机 key：

npx i18n-replace-react replace-key

4. 按 keys-map.json 替换 zh 目录下 messages 的 key：

npx i18n-replace-react replace-message-keys

5. 导出 Excel（供翻译团队使用）：

npx i18n-replace-react convert-excel

或者一键运行全部步骤：

npx i18n-replace-react all

常见问题与注意事项

• Node.js 版本：需要 Node.js >= 18（脚本使用 ESM 与顶层 await）。
• 备份：脚本会直接修改源码，请在运行前提交 git。
• keys-map.json：translate 会生成该文件；也可以手动准备并通过 KEYS_MAP 指定路径。
• 如果遇到找不到 keys-map.json 或 zh 目录的错误，可通过 KEYS_MAP/ZH_DIR 环境变量指定路径，或在项目根创建 keys-map.json。

代码位置概览

• app.js — 页面 + _components 提取入口
• components.js — components 目录提取入口
• translate.js — 将提取的中文翻译为 key（调用 DeepSeek）
• replace-key.js — 在源码中替换 t() 的 key
• replace-message-keys.js — 替换 zh 下 messages 的 key
• convert-excel.js — 导出 translations.xlsx
• lib.js — 公共工具（AST、读写、路径处理）