UI文字列
extractとtranslate-uiのリファレンス。これはt()呼び出しをロケールごとのカタログに変換するパイプラインです。初めてアプリにi18nを追加しますか?JS/TSアプリにi18nを追加する、Pythonアプリにi18nを追加する、または.NETアプリにi18nを追加するから始めてください。これらはラッピングステップをカバーし、その後ステップ2から4のためにここに戻ってきます。
このパイプラインは、JS/TSプロジェクト(React、Next.jsのクライアントおよびサーバーコンポーネント、Node.jsサービス、プレーンHTML、Astroウェブサイト、CLIツール)、Pythonアプリケーション、および.NETアプリケーションに対応しています。JS/TSは、ソースがt()を呼び出した後、i18nextで文字列を検索します。Pythonは、生成されたi18n.pyを介してt()またはgettextを呼び出します(DjangoはDjangoのgettextを維持します)。.NETは、生成されたI18n.csを介してT()を呼び出します。
読むべきガイド
| あなたのアプリ | 次に読むべきドキュメント |
|---|---|
ハードコードされたソース文字列があり、まだ t() がない JS/TS | JS/TS アプリに i18n を追加する |
ソースにすでに t() がある React / Next.js / Node | i18next を接続する |
Python (t()、_()、gettext、Jinja、Django) | Pythonアプリケーション。初期化: ui-python、ui-python-gettext、ui-python-flask、またはui-python-django。ヘルパー: i18n.py。既存のアプリにロケールを追加するには、Pythonアプリにi18nを追加するを参照してください。アプリがgettextを使用している場合は、Django / Python gettextアプリにi18nを追加するを参照してください。 |
.NET (T()、Tn、Tp、XAML loc:Tr) | .NETアプリケーション。初期化: ui-dotnet (I18n.cs) または ui-dotnet-resx (.NET ResourceManagerアプリにi18nを追加する)。既存のアプリにロケールを追加するには、.NETアプリにi18nを追加するを参照してください。 |
プレーンHTML (マークアップにt()なし) | プレーンHTMLアプリ |
| Astroマーケティングサイト (ハイブリッド) | Astroウェブサイト |
t()ルール、補間、複数形 | t()呼び出しと複数形 |
| 言語ピッカー / RTL | 言語スイッチャーとRTL |
| ランタイムAPIシグネチャ | ランタイムヘルパー |
Intlayer から移行する Intlayer .content.ts 辞書 | Intlayer からの移行 |
Intlayer を維持する Intlayer .content.ts 辞書 | Intlayer をインプレースで翻訳する |
ステップ1: 初期化
ai-i18n-tools init -P openrouterこれにより、ui-markdown テンプレート (そのプリセットの provider / providers ブロックを含む) を使用して ai-i18n-tools.config.json が書き込まれます。そのテンプレートは README.md のドキュメント翻訳も有効にし、translated-docs/ の下にフラットファイルとして書き込みます。README のみのリポジトリでは、代わりに init -t docs-markdown を使用します。README と Markdown ドキュメントに i18n を追加する を参照してください。translate-ui または sync を実行する前に、そのプロバイダーの API キーを環境または .env に設定します。ただし Ollama は例外です。プロバイダーと API キー を参照してください。UI 文字列には 4 つのキーが重要です。
sourceLocale: ソーステキストが書かれている言語の BCP-47 コードです。どの言語でも有効です。"en-GB"は一例にすぎません。ランタイム i18n 設定ファイル (src/i18n.ts/src/i18n.js) からエクスポートされたSOURCE_LOCALEと一致する必要があります。t()内の文字列はそのソース言語であり、フラットなロケールファイルはそれをキーとして使用します。targetLocales: ターゲット言語の BCP-47 コードです (例:["de", "fr", "pt-BR"])。generate-ui-languagesを実行して、このリストからui-languages.jsonマニフェストを作成します。ui.sourceRoots:t("…")の呼び出しをスキャンするディレクトリまたは glob パターンです (例:["src/"])。ui.stringsJsonとui.flatOutputDir: マスターカタログとロケールごとのファイル (de.json、pt-BR.json) が書き込まれる場所です。
providers.<active>.uiModels を含む他のすべてのキーは、設定 に記載されています。
ステップ2: 文字列を抽出する
t() / i18n.t() の呼び出しが存在するまで、extract は何も有用なことを行いません。まずハードコードされたコピーをラップしてください: JS/TS アプリに i18n を追加する。
ai-i18n-tools extractui.sourceRoots 以下のファイルをスキャンして t("literal") と i18n.t("literal") の呼び出しを探します。ui.stringsJson に書き込み (またはマージ) します。
スキャナーは設定可能です。ui.uiExtractor.funcNames (またはレガシーui.reactExtractor.funcNames) を介してカスタム関数名を追加します。Astroページとコンポーネントの場合、ui.uiExtractor.extensionsに.astroを追加します。プレーンHTMLについては、プレーンHTMLアプリを参照してください。
extract がスキャンするもの
- デフォルトの拡張子は
.js、.jsx、.ts、.tsxのみです。.mjs、.cjs、.mts、.ctsは、ui.uiExtractor.extensionsに追加した場合にのみ含まれます。 t(variable)のような非リテラルキーやテンプレートリテラルは、警告なしでスキップされます。package.jsondescriptionはデフォルトで含まれます (ui.uiExtractor.includePackageDescription)。- Vue と Svelte の単一ファイルコンポーネントはサポートされていません。
extensionsに.vueや.svelteを追加しても、テンプレートテキストは抽出されません。SFC パーサーはありません。
ステップ3: UI文字列を翻訳する
ai-i18n-tools translate-uistrings.jsonを読み込み、各ターゲットロケールに対し、アクティブなLLMプロバイダー上のモデルにバッチを送信し、ui.flatOutputDirにフラットなJSONファイル(de.json、fr.jsonなど)を書き込みます。モデルの選択には、UIチェーン:localeModels(locale) → uiModels → translationModelsを使用します(AIモデルを参照)。1つのロケール内では、最大uiBatchConcurrency個のバッチが同時に実行されます(デフォルトは2、設定 — uiBatchConcurrencyを参照)。-jは、依然としてターゲットロケールのみを並列化します。成功した各バッチは、次のバッチが開始する前にstrings.jsonとフラットなロケールファイルに書き込まれるため、実行を停止したり、後でAPIエラーが発生したりしても、既に完了したバッチは保持されます。
翻訳データベース (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の行を上書きする可能性があります。保存された翻訳がロケールの記述システムチェック(例:hiのローマ字表記ヒンディー語)に失敗したカタログ行は、欠落しているものとして扱われ、--forceなしで再翻訳されます。
ステップ 4: アプリで出力を使用する
translate-ui はファイルを書き込むだけです。アプリがそれらを読み込む必要があります。
- JS/TS: ランタイムヘルパーでi18nextを設定し、ユーザーが選択したロケールファイルをロードし、言語スイッチャーを追加します。i18nextを配線するおよび言語スイッチャーとRTLを参照してください。
- Python: 生成された
i18n.pyまたはgettextカタログを使用します。Pythonアプリケーションを参照してください。 - .NET: 生成された
I18n.csを使用するか、アプリがすでにResourceManagerを使用している場合はI18nResx.csを使用します。.NETアプリケーションおよび.NET ResourceManagerアプリにi18nを追加するを参照してください。migrate-dotnet-i18nは安全でないT()引数を書き換えます。--wrapはマークされていないラベルを監査します。 - プレーンHTML: ページの隣にランタイムスクリプトをロードします。プレーンHTMLアプリを参照してください。
- Astro: Astroウェブサイトを参照してください。
オプション
ロケールごとのモデルオーバーライド
モデルによっては、特定の言語の翻訳が得意なものがあります。例えば、qwenモデルやz-aiモデルはアジア言語の翻訳に優れています。各BCP-47ロケールに優先順位付けされたモデルリストを提供するために、providers.<active>.localeModelsエントリを追加します。これらのリストは、そのロケールに対してuiModelsとtranslationModelsよりも先に試行されます。ロケールタグは、大文字と小文字を区別せずに一致します(zh-cnとZH-CNは同等です)。一致するエントリがない場合、ツールはデフォルトのuiModelsとtranslationModelsの順序を使用します。同じlocaleModelsのメカニズムは、ドキュメント、JSON、SVGの翻訳にも適用されます。
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 はファイルの書き込みなしでパスを表示します。