Skip to content

クイックスタート ​

このページでは、単一言語プロジェクトを最初の翻訳ファイルに導きます。これは、JS/TSアプリ、Pythonアプリ、.NETアプリ、ウェブサイトまたはドキュメントサイト、あるいはリポジトリのREADMEやその他のMarkdownファイル向けです。前提条件は次のとおりです。

  • Node.js >=22.16.0、またはPythonまたは.NETプロジェクト用のスタンドアロン実行可能ファイル。
  • LLMプロバイダーのAPIキー、またはローカルのOllamaインストール。
  • プロジェクトはバージョン管理されているため、ツールが書き込む内容を確認できます。

プロジェクトによって異なる点が2つあります。ツールがテキストをどのように見つけるか、そしてアプリがその結果をどのように読み込むかです。以下のパスを選択から、それぞれに適したガイドに進んでください。

実行可能な例 ​

まずは完成したプロジェクトを見てみたいですか?リポジトリをクローンせずにコピーできます。

bash
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync

console-appを他のNode.jsの例に置き換えてください。Pythonおよび.NETの例にはpackage.jsonはありません。これらは同じ方法でコピーしてください。4つのPythonの例は、GitHubリリースにあるai-i18n-tools-python-examples.zipにも含まれており、2つの.NETの例はai-i18n-tools-dotnet-examples.zipにあります。各例が何を示すかを含む完全なリストは、例ページにあります。

インストール ​

bash
pnpm add -D ai-i18n-tools

npm install --save-dev ai-i18n-toolsとyarn add --dev ai-i18n-toolsも機能します。Pythonおよび.NETプロジェクトはスタンドアロン実行可能ファイルをインストールし、Node.jsは不要です。LinuxおよびmacOS: curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash。Windows PowerShell: irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex。その他のインストールオプション: インストール。

プロバイダーとAPIキー ​

LLMを呼び出す全てのコマンド(translate-ui、translate-docs、translate-json、translate-svg、sync)には、以下の両方が必要です。

  1. ai-i18n-tools.config.json に少なくとも 1 つのプロバイダーが必要です。これには translationModels を持つ providers.<name> ブロックが含まれ、複数のプロバイダーが設定されている場合はトップレベルの provider キーも必要です。init -P <provider> はそのプリセットをスキャフォールドします。プロバイダーを追加するには、LLM プロバイダー を参照してください。モデルリストを選択するには、AI モデル を参照してください。
  2. 対応する API キーを環境変数に設定するか、プロバイダーの API キーがまだ設定されていない場合は ai-i18n-tools.config.json と同じ階層にある .env / .env.local に設定する必要があります。各組み込みプリセットは、プリセットテーブル から名前付き変数を読み取ります。たとえば、OPENROUTER_API_KEY は -P openrouter を、OPENAI_API_KEY は -P openai を読み取ります。Ollama はローカルエンドポイントを使用するため、キーは不要です。
bash
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

LLMを呼び出さないextract、status、およびその他のコマンドでは、どちらも不要です。環境ファイルとPATHに関する詳細は、インストールを参照してください。

パスを選択 ​

ご自身のプロジェクトに合うものを見つけ、そのブロック内のコマンドを実行し、リンク先のガイドに進んでください。

JS/TSアプリ ​

この時点では、ボタンやメッセージはソース内でまだプレーンテキストであるため、ツールは何も見つけられません。まずそれらをt()でラップする必要があり、アプリには小さなi18next設定ファイルが必要です。

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --apply

次に、JS/TSアプリにi18nを追加するに進みます。このガイドでは、extractとtranslate-uiの前に、エージェントプロンプトを使用したラップ手順を説明します。

Pythonアプリ ​

bash
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --apply

その後、Pythonアプリにi18nを追加するに従ってください。

Djangoアプリ、Flask-Babelカタログを使用するFlask、またはすでにgettextを呼び出しているアプリは、それらの呼び出しを保持します。代わりに、ui-python-django、ui-python-flask、またはui-python-gettextでスキャフォールドし、その後、Django / Python gettextアプリにi18nを追加するに従ってください。

.NET アプリ ​

bash
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --apply

次に、.NETアプリにi18nを追加するに従ってください。すでにResourceManagerまたはIStringLocalizerを使用しているアプリは、代わりにui-dotnet-resxを使用し、次に.NET ResourceManagerアプリにi18nを追加するに従ってください。migrate-dotnet-i18nは、T($"…")を番号付きの{0}呼び出しに書き換えます。--wrapは、マークされていないXAMLおよびC#ラベルを監査します。レポートには、Resources.LoginButtonなどの名前付きresxキーが提案としてリストされ、それらの行は編集されません。

ウェブサイトまたはドキュメントサイト ​

お使いのフレームワーク用のテンプレートを選択してください。

サイトテンプレート
Astro Starlightui-starlight
Docusaurusui-docusaurus
VitePressui-vitepress
Nextraui-nextra
Fumadocsui-fumadocs
プレーンなAstroウェブサイトui-astro-website
プレーンなHTMLページui-plain-html または docs-plain-html
bash
ai-i18n-tools init -t ui-vitepress -P openrouter

その後、ウェブサイトまたはドキュメントサイトにi18nを追加するに従ってください。そのエージェントプロンプトは、フレームワークのi18nルーティングを有効にします。その作業を確認した後、syncを実行します。

READMEまたはMarkdownドキュメント ​

ほとんどのリポジトリでは、これをアプリと一緒に含めることが望まれます。デフォルトのui-markdownテンプレートには、すでにフラットなREADMEブロックが含まれています。その他のテンプレートの場合は、--with-readmeを追加します。Markdownのみのリポジトリではdocs-markdownを使用します。

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouter

次に、READMEとMarkdownドキュメントにi18nを追加するに従ってください。言語リストマーカーをsyncの前にREADME.mdに貼り付けます。アプリパスがある場合は、引き続きJS/TSアプリにi18nを追加する、Pythonアプリにi18nを追加する、または.NETアプリにi18nを追加するです。

その他 ​

  • そのまま維持されるネストされたi18next JSON: ai-i18n-tools init -t ui-json-bundles -P openrouterを実行し、その後JSONに従います。
  • テキストラベル付きのSVGダイアグラム: SVG翻訳。
  • Intlayerからの移行: Intlayerからの移行。
  • Intlayerを維持し、その翻訳のみを埋める場合: Intlayerのインプレース翻訳。

すべてのinitオプションを含むテンプレートの完全なリストは、CLIセットアップリファレンスにあります。

実行と確認 ​

プロジェクトの準備ができたら:

bash
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools status

doctorは、設定、パス、プロバイダー、および環境が準備できていることを確認します。--localを渡さない限り、プロバイダーでモデルIDも検証します。syncは、設定で有効になっているすべてのステップを順番に実行します。statusは、ロケールごとに何が翻訳されているかを表示します。ツールがテキストを認識できないプロジェクトで初回実行すると、エラーなしで終了し、何も有用なものを書き込みません。したがって、statusが文字列を表示しない場合は、パスのガイドに戻ってください。

suggest-models は、公開されているベンチマークからアクティブなプロバイダーのチャットモデルをランク付けします。suggest-models --apply は translationModels を置き換え、uiModels と localeModels はそのままにします。同じランキングがダッシュボードの モデル タブにあります。ランキングの仕組み、およびリストに複数のモデルが含まれる理由については、AI モデル を参照してください。コマンドリファレンス: suggest-models.

翻訳を維持する ​

ソーステキストが変更されるたびにsyncを再実行してください。SQLiteキャッシュにより、新規または変更されたテキストのみがモデルに送信されるため、再実行は低コストです。CIでsyncを実行すると、翻訳のずれを防ぐことができます。ai-i18n-tools dashboardで翻訳ダッシュボードを開き、キャッシュされた翻訳を確認・編集できます。

推奨されるpackage.jsonスクリプト ​

パッケージをローカルにインストールすると、追加のシェル設定なしで、スクリプトは node_modules/.bin から ai-i18n-tools を解決します。対話型シェルの場合は、最初にPATHを設定してください。CLIの使用 を参照してください。

json
{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:status": "ai-i18n-tools status",
  "i18n:statistics": "ai-i18n-tools statistics",
  "i18n:dashboard": "ai-i18n-tools dashboard",
  "i18n:cleanup": "ai-i18n-tools cleanup"
}

個々の翻訳スクリプトを連結するよりも sync を使用してください。1つのステップを単独で実行する必要がある場合にのみ、シングルステップのスクリプトを使用してください。

CLI出力とダッシュボードを別の言語で表示するには、-L <code>を渡すか、AI_I18N_LANGを設定します。ツールのUI言語を参照してください。

アプリの文字列とドキュメントサイトなど、複数の種類のコンテンツを一緒に翻訳しますか?パイプラインの結合 を参照してください。

次へ:パスの選択 にある、ご自身のパスに対応するガイド。

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