i18next-cli 🚀
SWC を採用した、統一された高性能な i18next CLI ツールチェーン。
デフォルトでは、
i18next-cliは JavaScript および TypeScript ファイル（.js、.jsx、.ts、.tsx）からのみ翻訳キーを抽出します。 他のファイルタイプ（.pug、.vue、.svelteなど）から抽出するには、プラグインを使用または作成する必要があります。extract.input設定に追加のファイル拡張子を指定するだけでは不十分です。非 JS/TS 形式にはプラグインが必要です。詳細と例については、プラグインシステム セクションを参照してください。
i18next-cli は、i18next エコシステム向けの静的解析ツールチェーンを完全に再構築したものです。主要な抽出、型安全性の生成、ロケール同期、リンティング、クラウド統合を、単一の凝縮された高速な 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 は、モダンな Web 開発の要求を満たすためにゼロから構築されています。
- 🚀 パフォーマンス： ネイティブ Rust ベースのパーサー（SWC）を活用することで、JavaScript ベースのパーサーよりも桁違いに高速なパフォーマンスを実現します。
- 🧠 インテリジェンス： ステートフルでスコープを認識するアナライザーが、
useTranslation('ns1', { keyPrefix: '...' })、getFixedT、エイリアスされたt関数などの複雑なパターンを正しく理解し、手動での回避策の必要性を最小限に抑えます。 - ✅ 統一ワークフロー： 単一のツール、単一の設定ファイル、単一の統合ワークフロー。さまざまな同期スクリプトを置き換えます。
- 🔌 拡張性： モダンなプラグインアーキテクチャにより、あらゆるフレームワークやカスタムワークフローに適応できます。
- 🧑💻 開発者体験： 完全に型付けされた設定ファイル、ライブ
--watchモード、CLI 出力、レガシーツールからの移行。
機能
- キー抽出: 抽出とは、ソースコード（JavaScript/TypeScript など）内で使用されているすべての翻訳キーを、コードの構造（AST）を解析して自動的に見つけ出し収集することを意味します。これにより、翻訳が必要なすべての文字列が特定され翻訳ファイルに含まれることが保証され、手作業を減らし、キーの欠落を防ぎます。
- 型安全性: TypeScript 定義を生成し、完全なオートコンプリートと型安全性を実現します。
- ロケール同期: すべての言語ファイルをプライマリ言語と同期させます。
- 正確なコードリンティング: 高い精度と設定可能なルールでハードコードされた文字列を検出します。
- 翻訳ステータス: プロジェクトの翻訳完了度に関する、高レベルの概要またはキーごとの詳細レポートを取得します。
- プラグインシステム: カスタム抽出パターンとファイルタイプ（例：HTML、Handlebars）のための拡張可能なアーキテクチャ。
- レガシー移行:
i18next-parser設定からの自動移行。 - クラウド統合: Locize 翻訳管理プラットフォームとのシームレスな統合。
インストール
npm install --save-dev i18next-cli
クイックスタート
1つのコマンドでゼロからローカライズ: ハードコードされた文字列を持つアプリ（例：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 拡張機能、翻訳者向け Web エディター Fink、Paraglide コンパイラ）が翻訳ファイルで直接動作できるようにします。対応するウィザードの質問をスキップします。
ウィザードは、設定ファイルの種類、ロケール、ソースファイルのグロブ、出力パス、そして最後に「翻訳バックエンド?」という3つの選択肢を尋ねます：
- ローカルファイルのみ（デフォルト）— 現在のローカル 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}} を使用する場合は名前空間オブジェクト形式で、名前空間はプライマリ言語のファイルから検出されます。それ以外の場合はプレーンなパターン）。また、.vscode/extensions.json の推奨事項に Sherlock 拡張機能を追加します（コメントを認識し、既存のエントリを上書きしないようにマージします）。i18next JSON ファイルは単一の信頼できる情報源のままです。inlang ツールはそれらをその場で読み書きするため、ドリフトする2番目のカタログはありません。既存の 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 });
ロガーを渡すと、スピナー出力とすべての進行状況/情報メッセージがインタラクティブスピナーではなくロガーにルーティングされます。
例:
# 1回限りの抽出
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（設定）: 報告されるべきではない（そしてチェックを失敗させない）キーのグロブパターン。例：一部のロケールで意図的に空のままにされているキー。オプションで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
…
[翻訳のため省略]