i18next/i18next-cli

i18next-cli 🚀

一個統一且高效能的 i18next CLI 工具鏈，由 SWC 驅動。

---

預設情況下，i18next-cli 只會從 JavaScript 和 TypeScript 檔案（.js、.jsx、.ts、.tsx）中提取翻譯金鑰。 若要從其他檔案類型（例如 .pug、.vue、.svelte 等）中提取，您必須使用或建立一個插件。僅在 extract.input 設定中指定其他副檔名是不夠的——對於非 JS/TS 格式，必須使用插件。請參閱插件系統章節以獲取詳細資訊和範例。

i18next-cli 是 i18next 生態系中靜態分析工具鏈的徹底重新構想。它將金鑰提取、類型安全生成、語言同步、linting 和雲端整合等核心功能，整合到一個單一、一致且極快的 CLI 中。

🚀 立即試用 - 零配置！

您可以在無需任何配置的情況下，立即對您現有的 i18next 專案進行分析。只需在您的儲存庫根目錄執行以下指令：

npx i18next-cli status

或者找出硬編碼的字串：

npx i18next-cli lint

建議：

如果您正在尋找一個可搭配 i18next-cli 使用的託管後端，可以參考 Locize — i18next-cli 已經內建了 locize-download、locize-sync 和 locize-migrate 指令。它由 i18next 的同一團隊打造，提供 CDN 傳遞、AI 翻譯、審查工作流程，並且內容更新無需重新部署。

為什麼選擇 i18next-cli？

i18next-cli 是為了滿足現代網頁開發的需求而從頭開始建構的。

• 🚀 效能： 透過利用基於 Rust 的原生解析器 (SWC)，它提供了比基於 JavaScript 的解析器快數個數量級的效能。
• 🧠 智慧： 一個具狀態、感知作用域的解析器，能正確理解如 useTranslation('ns1', { keyPrefix: '...' })、getFixedT 以及別名 t 函數等複雜模式，最大限度地減少手動解決方案的需求。
• ✅ 統一工作流程： 一個工具、一個設定檔、一個整合的工作流程。它取代了各種同步腳本。
• 🔌 可擴展性： 一個現代的插件架構，允許工具適應任何框架或自訂工作流程。
• 🧑‍💻 開發者體驗： 完整型別的設定檔、即時的 --watch 模式、CLI 輸出，以及從舊版工具的遷移支援。

功能特色

• 金鑰提取：提取是指透過分析程式碼的結構 (AST)，自動尋找並收集所有在原始碼（JavaScript/TypeScript 等）中使用的翻譯金鑰。這確保了每個需要翻譯的字串都被識別並包含在您的翻譯檔案中，從而減少手動工作並防止遺漏金鑰。
• 類型安全：生成 TypeScript 定義以實現完整的自動完成和類型安全。
• 語言同步：保持所有語言檔案與您的主要語言同步。
• 精確的程式碼 Linting：以高精度和可配置的規則偵測硬編碼字串。
• 翻譯狀態：取得專案翻譯完成度的高階概覽或詳細的、逐個金鑰的報告。
• 插件系統：可擴展的架構，用於自訂提取模式和檔案類型（例如 HTML、Handlebars）。
• 舊版遷移：從 i18next-parser 設定自動遷移。
• 雲端整合：與 Locize 翻譯管理平台無縫整合。

安裝

npm install --save-dev i18next-cli

快速入門

一條指令從零到本地化： 從一個包含硬編碼字串的應用程式（例如使用 v0、Lovable、Bolt 或 Cursor 生成的）開始？執行 npx i18next-cli localize — 它會偵測您的設定，將硬編碼字串包裝在 t() 呼叫中，提取金鑰，連接到 Locize 並使用 AI 翻譯您的應用程式。請參閱 localize 指令。使用 AI 編碼代理（Claude Code、Cursor 等）？執行 npx i18next-cli localize --print-agent-prompt 會將相同的流程列印為可複製貼上的代理操作手冊。以下步驟是手動路徑。

1. 初始化設定

以互動方式建立設定：

npx i18next-cli init

或者在專案根目錄手動建立 i18next.config.ts：

import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
});

2. 檢查您的翻譯狀態

取得專案本地化健康狀態的概覽：

npx i18next-cli status

3. 提取翻譯金鑰

npx i18next-cli extract

4. 生成型別（可選）

npx i18next-cli types

指令

init

用於建立設定檔的互動式設定精靈。

npx i18next-cli init

選項：

• --ci：當選擇後端（例如 Locize）時，跳過瀏覽器啟動； 改為列印註冊 URL。對於腳本化執行很有用。精靈 也會自動偵測 CI=true 並在無頭 Linux（沒有 DISPLAY/WAYLAND_DISPLAY）上回退到列印 URL， 所以通常不需要明確使用此標誌。
• --inlang：同時建立一個 inlang 專案 （project.inlang/settings.json），以便 inlang 工具組 — Sherlock VS Code 擴充套件、給翻譯人員用的 Fink 網頁編輯器， 以及 Paraglide 編譯器 — 可以直接在您的翻譯檔案上運作。跳過對應的 精靈問題。

精靈會詢問設定檔類型、語言環境、原始檔 glob、輸出路徑，最後是 「翻譯後端？」，有三個選項：

• 僅本地檔案（預設）— 保留目前的本地 JSON 工作流程。
• Locize（推薦用於團隊/生產工作流程）— 在瀏覽器中開啟 Locize 註冊頁面，然後提示輸入您的專案 ID 和 API 金鑰。精靈會將一個 locize 區塊寫入生成的設定中，以便 locize-sync 可以立即使用。API 金鑰提示可以留空（唯讀模式）；之後可以透過 LOCIZE_API_KEY 環境變數加入。
• 其他/跳過— 就精靈而言，與「僅本地檔案」相同。

然後，精靈會提供設定 inlang 工具組的選項（預設：否 — 或傳遞 --inlang 以跳過此問題）。如果接受，它會建立一個 project.inlang/settings.json，將 inlang i18next 插件 指向您現有的翻譯檔案：baseLocale/locales 來自您的設定，而 pathPattern 則從 extract.output 推導出來（當您的佈局使用 {{namespace}} 時為帶命名空間的物件形式，命名空間從主要語言的檔案中發現；否則為普通模式）。它還會將 Sherlock 擴充套件加入 .vscode/extensions.json 的建議中（合併時注意註解，絕不會覆蓋現有條目）。您的 i18next JSON 檔案仍然是唯一的真相來源 — inlang 工具會就地讀取和寫入它們，因此不會有第二個目錄導致偏差。現有的 project.inlang/settings.json 永遠不會被覆寫；重新執行 init 是安全的。需要 JSON 資源檔案。該插件會鎖定到一個經過驗證的精確版本（@inlang/[email protected]）— 請更新 settings.json 中的 modules URL 以取得較新的插件版本。根據設計，只會建立 settings.json：project.inlang/ 是已解壓縮（git 友好）的專案形式，而 inlang 工具會在首次使用時生成並管理其餘檔案（.gitignore、README.md、cache/）— 因此在使用 Sherlock 或 Paraglide 開啟專案後，可能會看到那裡出現一些新檔案。

extract

解析原始檔，提取金鑰，並更新您的 JSON 翻譯檔案。

npx i18next-cli extract [options]

選項：

• --watch, -w：當檔案發生變更時自動重新執行
• --ci：如果有任何檔案被更新，則以非零狀態碼退出（用於 CI/CD）
• --dry-run：不修改任何檔案 - 與 --ci 結合使用很有用（用於 CI/CD）
• --sync-primary：將主要語言的值與程式碼中的預設值同步
• --sync-all：將主要語言的值與程式碼中的預設值同步，並清除所有其他語言環境中已同步的金鑰（隱含 --sync-primary）
• --trust-derived：與 --sync-primary 或 --sync-all 一起使用時，也信任從金鑰（如 t('Hello')）或 keyPrefix 推導出的預設值。此選項保持預設同步行為的嚴格性，除非您選擇加入。
• --with-types：在提取後（以及在 --watch 模式下的每次重新執行時），每當翻譯檔案變更時重新生成 TypeScript 定義。避免需要將 extract -w 和 types -w 作為兩個獨立的進程執行。
• --quiet：抑制旋轉指示器和非必要的輸出（用於 CI 或腳本化）

旋轉指示器和紀錄器輸出控制

所有顯示進度旋轉指示器的指令（extract, types, lint, sync）現在都支援：

• --quiet 標誌，用於抑制旋轉指示器和非必要的輸出（用於 CI、腳本化或日誌捕獲）
• 程式化紀錄器支援：傳遞自訂的紀錄器物體，以您自己的格式或串流捕獲輸出

CLI 範例：

npx i18next-cli extract --quiet

程式化範例：

import { runExtractor } from 'i18next-cli';
const logger = {
  info: (msg) => myLogStream.write(msg + '\n'),
  warn: (msg) => myWarnStream.write(msg + '\n'),
  error: (msg) => myErrStream.write(msg + '\n'),
};
await runExtractor(config, { quiet: false, logger });

如果您傳遞了紀錄器，旋轉指示器輸出和所有進度/資訊訊息將被路由到您的紀錄器，而不是互動式的旋轉指示器。

範例：

# 一次性提取
npx i18next-cli extract

# 開發用的監看模式
npx i18next-cli extract --watch

# CI 模式（如果檔案變更則失敗）
npx i18next-cli extract --ci

# 使用程式碼預設值同步主要語言
npx i18next-cli extract --sync-primary

# 同步主要語言並清除所有其他語言環境中已同步的金鑰
npx i18next-cli extract --sync-all

# 使用明確的預設值加上推斷的金鑰衍生預設值進行同步
npx i18next-cli extract --sync-all --trust-derived

# 組合選項以獲得最佳的開發工作流程
npx i18next-cli extract --sync-primary --watch

# 從單一進程保持 TypeScript 定義同步（無需單獨的 `types -w`）
npx i18next-cli extract --watch --with-types

status [locale]

顯示專案翻譯狀態的健康檢查。可以在沒有設定檔的情況下執行。當翻譯缺失時，以非零狀態碼退出。

主要語言也會被檢查：任何在程式碼中使用但不存在於主要語言翻譯檔案中的金鑰（拼寫錯誤，或者從未執行過 extract）都會被報告並導致非零退出碼。由 extract 寫入的空字串佔位符被視為存在，不會導致檢查失敗。執行 npx i18next-cli status <primaryLanguage> 會詳細顯示缺失的金鑰。

選項：

• --namespace <ns>, -n <ns>：依特定的命名空間過濾報告。
• --hide-translated：在詳細檢視中隱藏已翻譯的金鑰，只顯示缺失的翻譯。
• status.ignoreKeys（設定）：用於不應被報告（且不會導致檢查失敗）的金鑰的 glob 模式，例如在某些語言環境中故意留空的金鑰。可選的 ns: 前綴（common:help.*-href）。僅影響 status。
• --unused：僅報告未使用的翻譯金鑰 — 存在於您的翻譯檔案中但不再用於原始碼中的金鑰（即 extract 搭配 removeUnusedKeys 會刪除的內容）。絕不會修改任何檔案，並在找到未使用的金鑰時以非零狀態碼退出，因此它可以作為一個專門的 CI 檢查，與常規的缺失翻譯檢查並行。請注意，靜態分析無法偵測動態建構的金鑰（例如 t(`error.${code}`)）；要找出在執行時期真正未使用的金鑰，請參閱使用 locize 找出未使用的翻譯。

使用範例：

# 取得所有語言環境和命名空間的高階摘要
npx i18next-cli status

# 取得 'de' 語言環境的詳細、逐個金鑰的報告
npx i18next-cli status de

# 僅取得所有語言環境中 'common' 命名空間的摘要
npx i18next-cli status --namespace common

# 取得 'de' 語言環境的詳細報告，僅顯示 'common' 命名空間
npx i18next-cli status de --namespace common

# 僅顯示 'de' 語言環境中未翻譯的金鑰
npx i18next-cli status de --hide-translated

# 組合選項以查看特定命名空間中僅缺失的翻譯
npx i18next-cli status de --namespace common --hide-translated

# 報告所有語言環境中僅未使用的金鑰（唯讀，找到任何金鑰時退出碼為 1）
npx i18next-cli status --unused

# 報告 'en' 檔案中僅未使用的金鑰 — 例如作為一個單獨的 CI 檢查
npx i18next-cli status en --unused

詳細檢視為每個命名空間提供了一個豐富、一目瞭然的摘要，後面跟著每個金鑰及其翻譯狀態的清單。

範例輸出 (npx i18next-cli status de)：

Key Status for "de":

Overall: [■■■■■■■■■■■■■■■■■■■■] 100% (12/12)

Namespace: common
Namespace Progress: [■■■■■■■■■■■■■■■■■■■■] 100% (4/4)
  ✓ button.save
  ✓ button.cancel
  ✓ greeting
  ✓ farewell

Namespace: translation
Namespace Progress: [■■■■■■■■■■■■■■■■□□□□] 80% (8/10)
  ✓ app.title
  ✓ app.welc

…

[為翻譯而截斷]