Skip to content

ドキュメント ​

translate-docs、Markdown、MDX、.astro、およびdocs[]設定ブロックにリストされているプレーンなHTMLページ用のパイプラインのリファレンスです。各ブロックのcontentPathsフィールドには、翻訳するファイルまたはフォルダーがリストされています。これらのファイルはsourceLocaleで書かれており、任意の言語を使用できます。例の英語は単なるサンプルです。初めてサイトに言語を追加しますか?ウェブサイトまたはドキュメントサイトにi18nを追加するから始めてください。リポジトリのREADMEやその他のMarkdownファイル(通常はアプリの隣にあるもの):READMEとMarkdownドキュメントにi18nを追加する。プレーンなHTMLページ(ロケールごとに1ファイル)については、HTMLページで説明されています。

フレームワークのシェル文字列(ナビゲーションバー、サイドバー、テーマ)は、別のパイプラインではなく、同じ実行で翻訳されます。以下の表にあるフレームワークガイドは、それぞれがどのように行うかを説明しています:Docusaurusの場合はdocusaurusCatalogDir、VitePressの場合はdocsOutput.vitepressThemeCatalog、Nextraの場合はdocs[].nextraDictionaryPath、Fumadocsの場合はdocsOutput.fumadocsUiCatalogです。Nextraの_meta.tsとFumadocsのmeta.jsonのサイドバーラベルは自動的に収集されます。Astro Starlightは多くのロケール向けに組み込みのUI文字列を提供しており、オプションの上書きはdocs[]ブロックでjsonPathTemplateを使用できます。

Markdownに埋め込まれたPNGやその他のラスター画像については、画像とスクリーンショットを参照してください。translate-docsは代替テキストのみを翻訳し、ラスターファイルをコピーしません。

README またはドキュメント内のオプションの 言語スイッチャー ブロックについては、docsOutput.style を "flat" に設定してください - 言語スイッチャー を参照してください。

SVG ファイルは、features.translateSVG が有効な場合に translate-svg を介して翻訳されます - docs[] / contentPaths は経由しません。

ドキュメントフレームワークのシェル/テーマ文字列とは無関係な任意のネストされたUI JSONバンドルは、docs[]ではなく、JSONパイプラインに属します。

各UIブロックには、デフォルトでドキュメント用の用語集ヒントとしてstrings.jsonが含まれます(uiGlossary、デフォルトはtrue)。translate-docsは、セグメントに一致する用語が登場した際に、それらの翻訳をLLMプロンプトのヒントとして再利用します。ドキュメントプロンプトに含めないカタログでは、uiGlossaryをfalseに設定します。オプションのglossary.userGlossaryにより、製品用語のCSVオーバーライドが追加されます(translate-uiおよびproofread-uiと共有)。狭い列に収めるために使用されるコンパクトなUIラベル略語(例:Size → Tam)は、UI翻訳では引き続き使用できますが、ドキュメントの用語集ヒントからは除外されます。glossary-generateでスターターCSVを生成し、翻訳ダッシュボードの用語集タブで行を編集するか、設定 — glossaryおよび用語集を参照してください。

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

translate-docs と sync の docs ステップは、ターゲットロケールごとにモデルを解決します。設定されている場合は localeModels(locale) が最初に、次にプロバイダーのグローバルな translationModels チェーンが使用されます。この機能は、特定の言語でデフォルトのフォールバックリストとは異なるモデルが必要な場合に使用します。例えば、グローバルチェーンがポルトガル語をうまく処理できない場合に、pt-BR ドキュメントには Gemini を優先的に使用するなどです。AI モデル および 設定 - localeModels を参照してください。

読むべきガイド ​

あなたのセットアップここから始める
Docusaurus サイトinit -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
VitePress サイトテーマ用に init -t ui-vitepress + vitepressThemeCatalog - VitePress
Nextra サイト辞書用に init -t ui-nextra + nextraDictionaryPath (サイドバー _meta.ts は自動) - Nextra
Fumadocs サイトUI 用に init -t ui-fumadocs + fumadocsUiCatalog (サイドバー meta.json は自動) - Fumadocs
Astro Starlightinit -t ui-starlight - Astro Starlight
プレーンHTMLページinit -t docs-plain-html - HTMLページ
フラットドキュメント(README、変更履歴など)READMEとMarkdownドキュメントにi18nを追加する — init -t docs-markdownまたは--with-readme。レイアウト:出力レイアウト、言語スイッチャー
翻訳されたファイルの保存場所出力レイアウト
ページ間の#anchorリンクアンカーリンク
リンクとアセットの URL 書き換え (regexAdjustments)リンクの書き換え
ドキュメント内のスクリーンショット画像とスクリーンショット
製品用語とUI/ドキュメントの一貫性設定 — glossary、用語集
translate-docsフラグとキャッシュCLIオプション

ステップ1: ドキュメントの初期化 ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai

Astro Starlight ドキュメントサイトの場合:

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference

VitePressドキュメントサイトの場合:

bash
ai-i18n-tools init -t ui-vitepress -P anthropic

ナビ/サイドバー/フッター文字列のために docsOutput.vitepressThemeCatalog を設定します - VitePress 統合 を参照してください。

Nextraドキュメントサイトの場合:

bash
ai-i18n-tools init -t ui-nextra -P gemini

テーマ辞書文字列のために docs[].nextraDictionaryPath を設定します - Nextra 統合 を参照してください。サイドバーの _meta.ts ラベルは自動的に収集されます。

Fumadocsドキュメントサイトの場合:

bash
ai-i18n-tools init -t ui-fumadocs -P groq

UI オーバーライドのために docsOutput.fumadocsUiCatalog を設定します - Fumadocs 統合 を参照してください。サイドバーの meta.json ラベルは自動的に収集されます。

プレーンなAstroウェブサイトUI(Starlightなし)の場合:

bash
ai-i18n-tools init -t ui-astro-website -P ollama

このテンプレートはUIの抽出のみを有効にします。ページHTMLの翻訳には、features.translateDocsも設定し、docs[]ブロックを追加してください(Astroウェブサイトページ(解析と置換)を参照)。examples/astro-website設定には、両方のパイプラインが一緒に示されています。

生成されたai-i18n-tools.config.jsonを編集します。

  • provider と providers — init -P <provider> がそのプリセットをスキャフォールドします。translate-docs または sync の前に API キーを設定してください (Ollama にはキーは不要です)。プロバイダーと API キー、LLM プロバイダー、AI モデル を参照してください。
  • sourceLocale - ソース言語 (docusaurus.config.js の defaultLocale と一致させる必要があります)。
  • targetLocales - BCP-47 ロケールコードの配列 (例: ["de", "fr", "es"])。
  • cacheDir - すべてのパイプラインで共有される SQLite キャッシュディレクトリ (および --write-logs のデフォルトのログディレクトリ)。
  • docs - ドキュメントブロックの配列。各ブロックにはオプションのdescription、contentPaths(文字列または配列、ファイル、ディレクトリ、またはglob)、outputDir、オプションのdocusaurusCatalogDir、docsOutput、オプションのsegmentSplitting、translateFrontmatterFields、protectAttributes、protectKeys、targetLocales、addFrontmatterなどがあります。
  • docs[].description - メンテナ向けのオプションの短いメモ。設定すると、translate-docsの見出しとstatusのセクションヘッダーに表示されます。
  • docs[].contentPaths - markdown/MDX/.astroソース(およびDocusaurusシェルJSON用のオプションのdocusaurusCatalogDir)。
  • docs[].outputDir - そのブロックの翻訳出力ルート。
  • docs[].docsOutput.style - "nested"(デフォルト)、"flat"、"doc-system"、またはエイリアス"docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs"(出力レイアウトを参照)。
  • ui[].uiGlossary - true(デフォルト)の場合、そのブロックのstrings.jsonがドキュメントセグメントの用語ヒントを提供します(設定 — uiを参照)。
  • glossary.userGlossary - 固定された製品用語翻訳用のオプションCSV。UIパイプラインでも使用され、ダッシュボードの用語集タブで編集可能です。

プライマリ対サプライメンタリ: ローカライズされたページには contentPaths を使用してください。write-translations から Docusaurus シェルの JSON も必要な場合は、docusaurusCatalogDir を設定します。ページの翻訳のみを行う場合は、docusaurusCatalogDir を省略してください。

ステップ2: ドキュメントを翻訳する ​

bash
ai-i18n-tools translate-docs

これは、すべての docs[] ブロックの contentPaths 内のすべてのファイル(および docusaurusCatalogDir が設定されている場合の Docusaurus カタログ JSON)を、すべての有効なドキュメントロケールに翻訳します。すでに翻訳されたセグメントは SQLite キャッシュから提供され、新規または変更されたセグメントのみが LLM に送信されます。

単一のロケールを翻訳するには:

bash
ai-i18n-tools translate-docs --locale de

翻訳が必要な内容を確認するには:

bash
ai-i18n-tools status

フラグ、キャッシュの動作、およびバッチプロンプトの形式については、CLIオプションを参照してください。

複雑なMarkdownと品質チェックの失敗 ​

translate-docsは、翻訳された各セグメントがMarkdownの構造(ドキュメントから解析された強調を含む)を保持し、内部のプレースホルダートークンが正しく復元されるかどうかをチェックします。`inline code`の周囲に多数のboldスパンを重ねたり、太字の中にバッククォートをネストしたり(例えば`fetch(\`/locales/${code}.json\`)`のようなテンプレートリテラル)、1つの長い文の中に太字とコードを織り交ぜたりする段落は脆弱です。一部のロケールでは異なる語順が必要になるため、翻訳後に**と`の並びが変わり、AST mismatchのようなCLIエラーがトリガーされる可能性があります。

復元後、translate-docs は、HTML タグのプレースホルダが再利用または削除された (その結果、復元されたタグがソースマップと一致しなくなる) セグメントや、モデルがソースになかった二重中括弧のトークン (たとえば、独自に作成された用語集形式のトークンなど) を生成したセグメントも拒否します。復元前のチェックでは、{{…}} トークンの同じ多重集合と、構造トークン ({{HTM_N}}、アドモニション マーカー) の同じ順序の部分シーケンスが要求されますが、{{ILC_N}}、{{URL_N}}、{{SE}} のような強調マーカーなどのコンテンツ トークンは、それぞれの ID/タイプの数が一致している場合、自然な語順に合わせて移動できます。これらの失敗は、残存した公式の内部トークンと同じモデル フォールバック パスを使用します。

そのような検証エラーが発生した場合は、ソース言語のテキストを簡略化することをお勧めします - 段落を分割する、例をコードブロックに移動する、または階層化された太字/コードのペアを減らして同じ概念を説明するなど - すべてのモデルとロケールが密集したインラインマークアップを完全に再現することを期待するのではなく。

セグメントに対して試行されたモデルがAST mismatchで失敗した場合、translate-docsは、そのセグメントをより小さな部分(まずリストの中央で、次に個々のリスト項目または短い段落の塊)に自動的に分割し、各部分を最初のモデルから再試行し、結果を元のセグメントキャッシュキーの下で再結合できます。同じ品質エラーが3回発生すると、モデルリストは早期に停止します。異なるエラーの場合は続行されます。これはデフォルトで有効になっています (segmentSplitting.qualityRetrySplit)。モデルリストの終了後に停止するには、falseに設定します。このフォールバックが実行されると、実行サマリーはQuality split retriesを報告します。

どのセグメントが失敗したか、その頻度、および保存されている品質/エラーメッセージを確認するには、翻訳ダッシュボードの失敗タブ(翻訳ダッシュボード → 失敗)を使用します。

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