@bitstack/i18n-manager-cli

前端專案與 i18n-manager 多語系雙向同步的 CLI。零相依，只用 Node 內建模組（需 Node ≥ 18）。

安裝

需 Node ≥ 18。擇一：

# 專案內安裝（建議 — 之後可用 npx i18n-cli 或 package.json scripts 呼叫）
pnpm add -D @bitstack/i18n-manager-cli
# npm / yarn 亦可
npm i -D @bitstack/i18n-manager-cli
yarn add -D @bitstack/i18n-manager-cli

# 或不安裝、直接執行
npx @bitstack/i18n-manager-cli pull

專案內安裝後，可在 package.json 加上 scripts 方便使用：

"scripts": {
  "i18n:push": "i18n-cli push",
  "i18n:pull": "i18n-cli pull",
  "i18n:sort": "i18n-cli sort"
}

初次使用提示：如果專案的語系檔已存在（例如曾經匯入 i18n-manager）， 請先執行 npx i18n-cli sort 將現有 key 的順序與線上對齊 — 該指令只調整順序、不會下載或修改任何線上資料。先 sort 並提交一次後， 之後 pull 的 diff 就只剩真正的內容變更，不會被順序差異淹沒。

設定

在前端專案根目錄放一份 i18n.config.json（可複製 i18n.config.example.json）：

{
  "host": "https://i18n-manager.example.com", // i18n 系統 API 域名
  "projectId": 123, // 專案 ID
  "token": "env:I18N_PAT", // 專案級別 PAT；建議用 env: 從環境變數讀
  "defaultLocale": "en-US", // status 比對用的基準語系
  "localesDir": "src/locales", // pull 寫入 {locale}.json 的目錄
  "localeMaps": {
    // 特定語系導到自訂路徑（相對 cwd，覆寫 localesDir）
    "scgc-en": "./complianceVersionR001/en", // manager 的 scgc-en → ./complianceVersionR001/en.json
  },
  "format": "nested", // nested | flat
  "interpolation": {
    // 插值佔位符雙向轉換；__VAR__ 標示變數位置
    "remote": "{{__VAR__}}", // 遠端（i18n-manager）儲存的格式
    "local": "{__VAR__}", // 本專案檔案的格式（單大括號；也可 ":__VAR__" 等）
  },
}

參數說明

| 參數 | 必填 | 預設 | 說明 | | --------------------- | :--: | ------------- | ----------------------------------------------------------------------------------------------------------------- | | host | ✅ | — | i18n-manager 的 API 域名（含 https://，尾端斜線可省）。 | | projectId | ✅ | — | 專案 ID。可在 i18n-manager「專案設定 → CLI 同步」查看。 | | token | ✅ | — | 專案級別同步 Token（PAT）。支援 env:VAR_NAME 從環境變數讀取，避免寫死進 repo。 | | defaultLocale | | en-US | status 比對用的基準語系。 | | localesDir | | src/locales | pull 寫入 / push 讀取 <locale>.json 的目錄（相對專案根目錄）。 | | localeMaps | | {} | 特定語系導到自訂路徑（相對專案根目錄，覆寫 localesDir），詳見下方章節。 | | format | | nested | nested（巢狀物件）或 flat（攤平 dot.path）。 | | interpolation | | 無（不轉換） | 插值佔位符雙向轉換設定，詳見下方章節。 | | interpolation.remote | | — | 遠端（i18n-manager）儲存的格式，如 {{__VAR__}}。__VAR__ 標示變數名稱位置。 | | interpolation.local | | — | 本專案檔案的格式，如 {__VAR__}、:__VAR__。 |

相容舊名：placeholder.{manager,project} 仍可用（等同 interpolation.{remote,local}），建議改用新名。

token 切勿寫死進 repo。用 env:I18N_PAT 由環境變數注入：export I18N_PAT=...。

語系路徑對應（localeMaps）

預設每個 manager 語系寫成 localesDir/<code>.json。若某語系要落到別的路徑（或改名），在 localeMaps 指定「manager 語系代碼 → 本地路徑」（相對專案根目錄，會覆寫 localesDir；沒有 .json 副檔名會自動補上）：

"localeMaps": {
  "scgc-en": "./complianceVersionR001/en"   // → ./complianceVersionR001/en.json
}

push / pull / status 都會依此對應讀寫該語系。

指令

| 指令 | 說明 | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | i18n-cli push [locale] | 讀 localesDir/<locale>.json，推到 manager。建立專案 key（已存在不覆蓋）+ 寫入該語系 value（可覆蓋）。locale 省略時推送 localesDir 內所有 *.json 加上 localeMaps 定義的語系。 | | i18n-cli pull [locale] | 從 manager 拉翻譯寫回本地。locale 省略拉全部語系。 | | i18n-cli status | 比對本地 base 與遠端，列出待 push 的新 key 與缺漏。 | | i18n-cli sort [locale] | 純本地重排語系檔的 key 順序，使其與 pull 輸出一致（keyPath 字母升序）。不連線、不改任何值。首次匯入後先跑一次，之後 pull 的 diff 就只剩真正的內容變更，不會被順序差異淹沒。locale 省略時重排 localesDir 內所有 *.json 加上 localeMaps 定義的語系。 |

開發流程（四步驟）

1. 看設計稿切版時，把文字設定到 localesDir/en-US.json（key + 英文值）。
2. i18n-cli push en-US — 專案 key 與 manager 對齊。
3. 進 i18n 工具 UI 對企劃語系檔做「同步綁定」。
4. i18n-cli pull — 專案取回全部語系。

既有專案（語系檔已匯入過 i18n-manager）初次接上 CLI 時，先跑一次 i18n-cli sort 對齊 key 順序再開始 pull，diff 才乾淨。

插值佔位符轉換（interpolation）

push 時把本地格式（local）轉成遠端格式（remote），pull 時反向。__VAR__ 是變數名稱位置的標記：

• i18next："remote": "{{__VAR__}}"
• 單大括號："local": "{__VAR__}"
• 具名冒號：":__VAR__"

remote 與 local 相同（或未設定 interpolation）時不做轉換。舊名 placeholder.{manager,project} 仍相容。