ドキュメント
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 Starlight | init -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: ドキュメントの初期化
ai-i18n-tools init -t ui-docusaurus -P openaiAstro Starlight ドキュメントサイトの場合:
ai-i18n-tools init -t ui-starlight -P cheaperinferenceVitePressドキュメントサイトの場合:
ai-i18n-tools init -t ui-vitepress -P anthropicナビ/サイドバー/フッター文字列のために docsOutput.vitepressThemeCatalog を設定します - VitePress 統合 を参照してください。
Nextraドキュメントサイトの場合:
ai-i18n-tools init -t ui-nextra -P geminiテーマ辞書文字列のために docs[].nextraDictionaryPath を設定します - Nextra 統合 を参照してください。サイドバーの _meta.ts ラベルは自動的に収集されます。
Fumadocsドキュメントサイトの場合:
ai-i18n-tools init -t ui-fumadocs -P groqUI オーバーライドのために docsOutput.fumadocsUiCatalog を設定します - Fumadocs 統合 を参照してください。サイドバーの meta.json ラベルは自動的に収集されます。
プレーンなAstroウェブサイトUI(Starlightなし)の場合:
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: ドキュメントを翻訳する
ai-i18n-tools translate-docsこれは、すべての docs[] ブロックの contentPaths 内のすべてのファイル(および docusaurusCatalogDir が設定されている場合の Docusaurus カタログ JSON)を、すべての有効なドキュメントロケールに翻訳します。すでに翻訳されたセグメントは SQLite キャッシュから提供され、新規または変更されたセグメントのみが LLM に送信されます。
単一のロケールを翻訳するには:
ai-i18n-tools translate-docs --locale de翻訳が必要な内容を確認するには:
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を報告します。
どのセグメントが失敗したか、その頻度、および保存されている品質/エラーメッセージを確認するには、翻訳ダッシュボードの失敗タブ(翻訳ダッシュボード → 失敗)を使用します。