magic-i18next

一套面向前端工程的 i18n 自动化工具集。

我相信你也有这样的烦恼：前端做国际化项目，有大量的体力活...

包括 想key名、手动替换key。如果涉及的国家比较多的话，还要挨个语言复制粘贴...命名已经开发完了，为了这个多语言又得花个半天时间搞。

虽然现在可以雇一个Ai帮你干，但是想要完全脱手还是不太放心。

该项目就是为了做多语言的时候，完全脱手，让你拥有接近单一语言的开发体验。 也就是说你只管像原来开发单一语言那样开发，其它交给它。它会自动抽离出文本，交给别人(or Ai)去做。

我看了市面上也有不少类似的工具，但是都很繁重，还要后台管理 权限配置 数据分析 一大堆。我只想翻个译，给我搞这么拖家带口的，为了收费也是拼了...

如果你和我一样，项目不是特别特别大，强烈推荐！该工具就是配置简单，快速上手。

简单说明：

就是将项目中的文本都用 $k(``) 包裹，执行脚本，$k(``) 变成了 $k``, $k内部结合相关i18n相关库实现翻译。举个例子：

$k(`这是文本`)  -->  $k`auto.1__这是文本`

该项目覆盖：

• conversion（rep）：扫描源码，提取文案并替换为可国际化调用（生成/更新 src/locales/*.json）
• json2Excel：把本地多语言 JSON 导出为 Excel
• excel2Json：把 Excel 导入/同步回本地多语言 JSON
• feishu：本地 JSON ↔ 飞书多维表格（push/pull，全量同步、排序、进度、限流）
• google-sheets：本地 JSON ↔ Google Sheets（push/pull，全量同步、排序、进度、代理）
• deepSeek: 接入deepSeek大模型实现同步翻译

快速开始

环境要求

• Node.js 20+（推荐 22+）

安装依赖

我这里用的是yarn, 当然你们可以自选其他的比如npm也行。

yarn

配置：magic-i18next.config.ts

项目核心配置都在 magic-i18next.config.ts。

通用配置

• scanDir：默认扫描目录（不传参执行 rep 时会从这里递归扫描）
• extensions：扫描的扩展名
• exclude：排除目录/文件名
• outputDir：生成 *.json 的目录（例如 ./src/locales）
• defaultLanguage：默认语言（例如 cn）

飞书：feishuConfig

用于 yarn push / yarn pull（飞书多维表格同步）：

• appId / appSecret
• appToken / tableId
• localeDir：本地 JSON 目录（不填则用 outputDir）
• fieldMap：语言代码 → 飞书列名（如 { cn: '中文', en: 'English' }）
• keyFieldName：key 列名（脚本会尝试把默认「文本」列改名为 key）
• statusFieldName：状态列名（单选：待处理/已处理）

Google Sheets：googleSheetsConfig

用于 yarn push:google / yarn pull:google：

• spreadsheetId
• credsPath：service account json 路径
• localeDir：本地 JSON 目录（不填则用 outputDir）
• sheetIndex：使用第几个 sheet（从 0 开始）
• proxy：国内访问 Google 建议开启（默认 http://127.0.0.1:10808）

代理也支持环境变量（优先级更高）：

setx HTTPS_PROXY "http://127.0.0.1:10808"
setx HTTP_PROXY "http://127.0.0.1:10808"

模块使用方式

1) conversion（rep）：扫描并替换 + 生成 locales

默认全盘扫描（按 scanDir）：

node build/conversion/index.js

指定目录扫描：

node build/conversion/index.js ./src/test

指定文件扫描：

node build/conversion/index.js ./src/test/test.ts

说明：

• 会提示输入语言（30 秒超时后使用 defaultLanguage）
• 会生成/更新 outputDir/<lang>.json

2) json2Excel：JSON → Excel

构建后运行：

node build/json2Excel/index.js

常见用途：

• 把 src/locales/*.json 汇总为 Excel 交给产品/翻译

3) excel2Json：Excel → JSON

构建后运行：

node build/excel2Json/index.js

常见用途：

• 把翻译后的 Excel 导回本地 src/locales/*.json

4) 飞书多维表格（Feishu）

Push：本地 JSON → 飞书（全量同步）

yarn push

特性：

• 全量同步：本地有多少条，飞书就有多少条（会自动删除云端多余记录）
• 缺失列自动创建：语言列缺失会自动补；状态列为单选（待处理/已处理）
• key 列处理：如果存在默认“文本”列，会尝试改名为 key
• 排序规则：auto.* 在前、extra.* 永远在后，并按数字顺序
• 进度/限流：批量 + sleep，避免频率限制

Pull：飞书 → 本地 JSON（强制覆盖）

yarn pull

5) Google Sheets

Push：本地 JSON → Google Sheets（全量同步）

yarn push:google

说明：

• 为了保证 行顺序严格正确（auto 在前、extra 在后），脚本会：
  • 先清空数据区（保留表头）
  • 再按排序重写全部行
• 空字符串兼容：写入时会用零宽空格占位，拉取时会还原为 ""

Pull：Google Sheets → 本地 JSON（强制覆盖）

yarn pull:google

常见问题（FAQ）

1) push:google 超时 / 很慢

• 确认已配置代理（环境变量或 googleSheetsConfig.proxy）
• 确认你的代理是 http（当前脚本不支持 socks5）

2) push:google 报 403

说明 service account 没有表格权限：把 google-creds.json 里的 client_email 加到 Google Sheet 的共享里，并给编辑权限。