Skip to content

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/TSJS/TS アプリに i18n を追加する
ソースにすでに t() がある React / Next.js / Nodei18next を接続する
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: 初期化 ​

bash
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 を追加する。

bash
ai-i18n-tools extract

ui.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.json description はデフォルトで含まれます (ui.uiExtractor.includePackageDescription)。
  • Vue と Svelte の単一ファイルコンポーネントはサポートされていません。extensions に .vue や .svelte を追加しても、テンプレートテキストは抽出されません。SFC パーサーはありません。

ステップ3: UI文字列を翻訳する ​

bash
ai-i18n-tools translate-ui

strings.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 はファイルを書き込むだけです。アプリがそれらを読み込む必要があります。

オプション ​

ロケールごとのモデルオーバーライド ​

モデルによっては、特定の言語の翻訳が得意なものがあります。例えば、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 を呼び出したりすることはありません。

bash
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 はファイルの書き込みなしでパスを表示します。

MITライセンスの下で公開されています。