UI文字列
i18nextを使用するあらゆるJS/TSプロジェクト向けに設計されています：Reactアプリ、Next.js（クライアントおよびサーバーコンポーネント）、Node.jsサービス、プレーンHTML、Astroウェブサイト、CLIツール。
読むべきガイド
| あなたのアプリ | 次を読む |
|---|---|
| React / Next.js / Node + i18next | i18nextを接続する (ステップ4) |
プレーンHTML (マークアップにt()なし) | プレーンHTMLアプリ |
| Astroマーケティングサイト (ハイブリッド) | Astroウェブサイト |
t()ルール、補間、複数形 | t()呼び出しと複数形 |
| 言語ピッカー / RTL | 言語スイッチャーとRTL |
| ランタイムAPIシグネチャ | ランタイムヘルパー |
ステップ1: 初期化
ai-i18n-tools init [-P <provider>]これにより、ui-markdown テンプレートを使用して ai-i18n-tools.config.json が書き込まれます（デフォルトの provider / providers ブロックを含む）。translate-ui または sync を実行する前に、環境変数または .env でアクティブなプロバイダーのAPIキーを設定してください（Ollamaを除く）。プロバイダーとAPIキーを参照してください。設定を編集して以下を設定します：
providerおよびproviders—translationModelsを持つプロバイダが少なくとも1つ必要です。デフォルトがお好みでない場合は、プリセットまたはモデルリストを変更してください (init -P <provider>)。LLMプロバイダとモデルを参照してください。sourceLocale- ソース言語のBCP-47コード（例："en-GB"）。ランタイムi18nセットアップファイル（src/i18n.ts/src/i18n.js）からエクスポートされたSOURCE_LOCALEと一致する必要があります。targetLocales- ターゲット言語のBCP-47コードの配列（例：["de", "fr", "pt-BR"]）。このリストからui-languages.jsonマニフェストを作成するには、generate-ui-languagesを実行します。ui.sourceRoots-t("…")呼び出しをスキャンするディレクトリまたはglobパターン（例：["src/"]、["src/**/*.ts"]）。ui.stringsJson- マスターカタログを書き込む場所（例:"src/locales/strings.json"）。ui.flatOutputDir-de.json、pt-BR.jsonなどを書き込む場所（例:"src/locales/"）。providers.<active>.uiModels（オプション） -translate-ui、複数形生成、およびproofread-uiのための順序付きUI専用モデルリスト（一致するlocaleModelsエントリの後、translationModelsの前）。プロバイダーとモデルを参照してください。
ステップ2: 文字列を抽出する
ai-i18n-tools extractui.sourceRoots 配下のすべての JS/TS ファイルをスキャンし、t("literal") および i18n.t("literal") 呼び出しを検出して ui.stringsJson に書き込み（またはマージ）します。
スキャナーは設定可能です。ui.uiExtractor.funcNames (またはレガシーui.reactExtractor.funcNames) を介してカスタム関数名を追加します。Astroページとコンポーネントの場合、ui.uiExtractor.extensionsに.astroを追加します。プレーンHTMLについては、プレーンHTMLアプリを参照してください。
ステップ3: UI文字列を翻訳する
ai-i18n-tools translate-uistrings.jsonを読み取り、各ターゲットロケールのアクティブなLLMプロバイダーにバッチを送信し、フラットなJSONファイル（de.json、fr.jsonなど）をui.flatOutputDirに書き込みます。モデル選択にはUIチェーンが使用されます: localeModels(locale) → uiModels → translationModels（「プロバイダーとモデル」を参照）。
ロケールごとのモデルオーバーライド
ターゲット言語によっては、一部の翻訳モデルが他のモデルよりも大幅に優れたパフォーマンスを発揮する場合があります。例えば、多くの西洋（欧米系）言語モデルと比較して、qwenやz-aiモデルはアジア言語に対してより高品質な翻訳を生成する傾向があります。これを活用するために、オプションのproviders.<active>.localeModelsエントリを使用して、各BCP-47ロケールの優先順位付けされたモデルリストを指定できます。これらのモデルリストは、その特定のロケールに対して、より一般的なuiModelsおよびtranslationModelsよりも先に試行されます。これにより、モデルの選択を調整し、言語ごとに翻訳品質を向上させることができます。ロケールタグは大文字と小文字を区別せずに一致します（したがって、zh-cnとZH-CNは同等です）。カスタムエントリがロケールに一致しない場合、ツールはUI翻訳用のデフォルトのuiModelsおよびtranslationModelsの順序にフォールバックします。同じlocaleModelsメカニズムは、ドキュメント、JSON、およびSVGの翻訳にも適用されます。
翻訳データベース (strings.json)
各エントリについて、translate-uiは、オプションのmodelsオブジェクト (translatedと同じロケールキー) 内で、各ロケールを正常に翻訳したアクティブプロバイダーからのモデルIDを格納します。翻訳ダッシュボードで編集された文字列は、そのロケールのmodelsで、番兵値user-editedでマークされます。ui.flatOutputDirの下にあるロケールごとのフラットファイルは、ソース文字列 → 翻訳のみのままであり、modelsは含まれません (そのため、ランタイムバンドルは変更されません)。
注: UI文字列に対するダッシュボードの編集は、SQLiteドキュメントキャッシュではなく、
strings.jsonに保存されます。カタログからフラットロケールファイルを書き換えるには、プレーンなsyncまたはtranslate-ui(特別なフラグなし) を実行します。--force-updateはUIステップに転送されません。手動編集後にUIコマンドで--forceを使用しないでください。すべてのエントリが再翻訳され、user-edited行が上書きされる可能性があります。
次に、実行時にi18nextを接続します — i18nextを接続する。
XLIFF 2.0へのエクスポート (オプション)
UI 文字列を翻訳ベンダー、TMS、CAT ツールに引き渡すために、カタログを XLIFF 2.0 形式（ターゲットロケールごとに1ファイル）でエクスポートします。このコマンドは読み取り専用です。strings.json を変更したり、API を呼び出したりすることはありません。
ai-i18n-tools export-ui-xliffデフォルトでは、ファイルは ui.stringsJson の隣に strings.de.xliff、strings.pt-BR.xliff（カタログのベースネーム + ロケール + .xliff）のような名前で出力されます。-o / --output-dir を使用して他の場所に出力できます。strings.json からの既存の翻訳は <target> に表示され、翻訳のないロケールは <target> なしの state="initial" として出力され、ツールが翻訳を埋められるようになります。--untranslated-only を使用すると、各ロケールでまだ翻訳が必要なユニットのみをエクスポートできます（ベンダー向けのバッチ処理に便利です）。--dry-run はファイルの書き込みなしでパスを表示します。