ウェブサイトまたはドキュメントサイトにi18nを追加する
このページは、単一言語のドキュメントサイト (Markdown または MDX) や、マーケティングサイトまたは静的サイト (Astro ウェブサイトまたはプレーン HTML) を対象としています。このツールは、お使いの LLM プロバイダーのモデルでページコンテンツを翻訳し、言語ごとにローカライズされたコピーを1つ書き出します。サイトのフレームワークがそれらのコピーを配信し、言語スイッチャーを提供します。
UI文字列がt()呼び出しにあるアプリの場合は、代わりにJS/TSアプリにi18nを追加するまたはPythonアプリにi18nを追加するを使用してください。
どのようなものをお持ちですか？
| あなたのサイト | 初期テンプレート | ここから開始 |
|---|---|---|
| Astro StarlightまたはプレーンなAstro | ui-starlight / ハイブリッドUI文字列 | Astro |
| Docusaurus | ui-docusaurus | Docusaurus |
| VitePress | ui-vitepress | VitePress |
| Nextra 4 (Next.js App Router) | ui-nextra | Nextra |
| Fumadocs 4 (Next.js App Router) | ui-fumadocs | Fumadocs |
| プレーンなHTMLページ | ui-plain-html または docs-plain-html | プレーンなHTMLアプリ |
| サイトフレームワークなし、READMEとMarkdownファイルのみ | docs-markdown、または任意のテンプレートと--with-readme | READMEとMarkdownドキュメントにi18nを追加する |
エージェントプロンプト
- Astro Starlight: 注記のみ。Astro
t()ファイル: JS/TSプロンプト (i18nextをスキップ)。 - Docusaurus: 注記のみ（
<Translate>はDocusaurus独自のAPIです）。 - VitePress: テーマカタログプロンプト。
- Nextra: ディクショナリプロンプトとハイブリッド
t()プロンプト。 - Fumadocs: UIカタログプロンプト。
- READMEとMarkdownファイル: READMEプロンプト。
手順
同じ形式がすべてのフレームワークで機能します。詳細については、上記のフレームワークガイドを参照してください。
- CLIをインストールし、APIキーを設定します: インストール、プロバイダーとAPIキー。
- スキャフォールド:
ai-i18n-tools init -t <template> -P <provider>。 sourceLocale、targetLocales、およびdocs[].contentPaths（ソース言語で書かれたページとフォルダー）を設定します。sourceLocaleは任意の言語にできます。フレームワークガイドには適切なdocsOutput.styleが示されています。- フレームワーク独自のi18nを有効にして、ローカライズされたページを提供し、リンクするようにします。各ガイドには「既存のサイトでi18nを有効にする」セクションがあります: VitePress、Docusaurus、Nextra、Fumadocs、Astro。
ai-i18n-tools sync（またはtranslate-docs）を実行し、サイトをビルドします。- ブラウザでローカライズされたルートを確認します。フレームワーク独自のロケールドロップダウンがスイッチャーです。READMEのようなフラットなMarkdownファイルの場合は、languageListBlockを使用してリンク行を追加します。
何が翻訳されるか
ページ本文は常にドキュメントパイプラインを通過します。フレームワークのクローム（ナビゲーション、サイドバー、テーマラベル）は、フレームワークがサポートしている場合は同じ実行で処理され、個別のJSONパイプラインを介しては処理されません。
| フレームワーク | シェルとテーマの文字列 | 方法 |
|---|---|---|
| Docusaurus | write-translationsカタログ ({ message, description }) | docs[].docusaurusCatalogDirとtranslate-docs |
| VitePress | テーマ、ナビゲーション、サイドバーのカタログ | docsOutput.vitepressThemeCatalogとtranslate-docs |
| Nextra | _meta.tsサイドバーラベル | style: "nextra"で自動 |
| Nextra | テーマディクショナリ.ts | docs[].nextraDictionaryPath |
| Fumadocs | meta.jsonサイドバーラベル | style: "fumadocs"で自動 |
| Fumadocs | UIのオーバーライドカタログ | docsOutput.fumadocsUiCatalog |
| Astro Starlight | 多くのロケールに組み込まれたUI文字列 | ページのみ |
画像とスクリーンショットはtranslate-docsによって翻訳されません。ロケール固有のファイルについては、画像とスクリーンショットを参照してください。
プレーンHTML
ページの動作に応じて、2つのオプションがあります。
- ブラウザで言語を切り替える1つのページの場合：テキストに
data-i18n*属性をマークし、UI文字列ランタイム (ui-plain-html) を使用します。プレーンHTMLアプリを参照してください。 - ロケールごとに1つの翻訳済みHTMLファイルの場合：ドキュメントパイプライン (
docs-plain-html) を使用します。HTMLページを参照してください。
ファイルは1つのパスに属します。
当てはまりませんか？
- アプリのUI文字列：JS/TSアプリにi18nを追加 または Pythonアプリにi18nを追加。
- サイトの隣にあるリポジトリのREADME、またはMarkdownファイルでサイトフレームワークがない場合：READMEとMarkdownドキュメントにi18nを追加。
init … --with-readmeは、サイトテンプレートの横にそのブロックを追加します。 - スタンドアロンのネストされたロケールJSON：JSON。
- サイトとアプリの文字列の両方を翻訳する場合：パイプラインの結合。
共有オプションとフレームワークごとの違いに関するリファレンス：インテグレーション。