magic-i18next

Appearance

配置 Google Sheets ​

1) 创建 Google Cloud 项目并启用 API ​

  1. 打开 Google Cloud Console 并创建项目（或使用已有项目）。
  2. 在“API 和服务”中启用这两个 API：
    • Google Sheets API
    • Google Drive API

这两个都建议开启。Sheets API 负责读写内容，Drive API 常用于文件访问相关能力。

2) 创建 Service Account 并下载 JSON 密钥 ​

  1. 进入“API 和服务” -> “凭据”。
  2. 点击“创建凭据” -> “服务账号 (Service Account)”。
  3. 创建后进入该服务账号详情页，点击“密钥 (Keys)”。
  4. 点击“添加密钥” -> “创建新密钥”，选择 JSON，下载到本地。

下载后的 JSON 文件里会包含 client_email、private_key 等字段，这就是后面 credsPath 要指向的文件。

3) 创建 Google Sheet 并授权给服务账号 ​

  1. 新建一个 Google Sheet（或使用已有表格）。
  2. 点击右上角“共享”。
  3. 把刚才 JSON 里的 client_email 添加为“编辑者 (Editor)”权限。

如果不做这一步，脚本通常会报 403（没有权限访问表格）。

4) 获取 spreadsheetId ​

表格 URL 形如：

https://docs.google.com/spreadsheets/d/<spreadsheetId>/edit#gid=0

其中 <spreadsheetId> 就是配置里要填的 spreadsheetId。

5) 配置 magic-i18next.config.ts ​

ts
googleSheetsConfig: {
  spreadsheetId: '你的表格ID',
  credsPath: './src/google-sheets/google-creds.json',
  sheetIndex: 0,
  localeDir: './src/locales',
  // 中国大陆网络环境常需要代理
  proxy: { protocol: 'http', host: '127.0.0.1', port: 10808 },
},

字段说明：

  • spreadsheetId：Google Sheet 的 ID。
  • credsPath：服务账号 JSON 文件路径（相对项目根目录）。
  • sheetIndex：第几个 sheet，默认从 0 开始。
  • localeDir：本地语言 json 目录，不填则走默认目录。
  • proxy：可选。网络需要代理时再配置。

6) 同步命令 ​

先把本地内容推到 Google Sheets：

bash
npx magic push:google

翻译完成后再拉回本地：

bash
npx magic pull:google

注意：push 和 pull 都是覆盖式更新，执行前建议先用 git 提交或备份。

常见问题排查 ​

  1. 403 权限错误

    • 检查表格是否共享给了服务账号邮箱，并且权限是编辑者。

  2. 找不到凭据文件 (ENOENT)

    • 检查 credsPath 路径是否正确，文件是否在项目内可访问。

  3. 认证失败 (invalid_grant)

    • 检查服务账号 JSON 是否完整、未损坏，系统时间是否正确。

  4. 超时或连不上 Google

    • 在 googleSheetsConfig.proxy 中配置本机代理参数。