アーキテクチャ
アーキテクチャの概要
コードベースは4つのレイヤーで構成されています。このセクションは概念モデルとして使用し、ファイルレベルの詳細が必要な場合はソースツリーを開いてください。
syncの実行の仕組み
sync(および個々の翻訳コマンド)は、有効な機能を次の順序で実行します。
| ステップ | コマンド | 実行内容 |
|---|---|---|
| 1 | extract → translate-ui | UIソースのスキャン → strings.jsonの更新 → フラットなロケールJSON(de.jsonなど)の入力 |
| 2 | translate-svg (オプション) | config.svg配下のSVGテキストを翻訳 |
| 3 | translate-docs | Markdown、MDX、.astro ページを翻訳。Docusaurus カタログ JSON。Nextra _meta / 辞書 .ts。VitePress テーマカタログ |
| 4 | translate-json (オプション) | json[]配下のネストされたJSONリーフを翻訳 |
すべてのパイプラインは、セグメントの抽出 → 構文の保護 → バッチ処理 → キャッシュ検索またはLLM呼び出し → 出力の書き込みという同じコアループに従います。設定、プレースホルダー、キャッシュ、用語集、LlmClientなどの中央の共有サービスについては、共有インフラストラクチャで説明しています。
モジュールマップ
| レイヤー | フォルダー | 役割 |
|---|---|---|
| エントリ | src/cli/ | CLIコマンド: init、extract、mark-html、translate-ui、translate-docs、translate-json、translate-svg、sync、status、dashboard、… |
| パイプライン | src/extractors/ | JS/TS、HTMLマーカー、Markdown、JSON、SVG、.astroからのセグメント抽出 |
src/processors/ | プレースホルダー保護、バッチ処理、検証、リンク書き換え | |
| 共有 | src/core/ | 設定、型、SQLiteキャッシュ、プロンプト、出力パス、ロケールユーティリティ |
src/api/ | LlmClient — プロバイダーに依存しないチャットクライアント(Vercel AI SDK)、モデルフォールバック付き | |
src/glossary/ | プロンプト用の用語集読み込み、用語ヒント、およびオプションのプロジェクトコンテキストファイル | |
src/utils/ | ロガー、ハッシュ化、無視パーサー、表示幅テーブル、.envローダー | |
| アプリのランタイム | src/runtime/ | i18nextヘルパーと表示ユーティリティ — 'ai-i18n-tools/runtime'としてエクスポートされます(ランタイムヘルパー) |
| ツールUI (ドッグフーディング) | src/i18n/、src/dashboard-app/、src/server/ | このパッケージ自身のCLIと翻訳ダッシュボードをローカライズします — プロジェクトコンテンツとは別に(自己ローカライズ) |
プログラムによる使用を目的としたものはすべてsrc/index.tsから再エクスポートされます(プログラムAPI)。
パイプラインの概要
| パイプライン | セクション | 入力 → 出力 |
|---|---|---|
| UI 文字列 | UI 文字列の内部 | ソースファイル → strings.json → フラットな {locale}.json |
| ドキュメント | ドキュメントの内部 | Markdown / MDX / .astro / Docusaurus JSON → docs[].outputDir 以下のロケールごとのファイル |
| JSON バンドル | JSON の内部 | json[] 以下のネストされた JSON → ロケールごとの JSON ファイル |
| SVG | ドキュメントの内部 — エクストラクター | config.svg 以下の SVG ファイル → 翻訳された SVG コピー |
UI 文字列の内部構造
| ステップ | コンポーネント | 結果 |
|---|---|---|
| 1 | ソースファイル (JS/TS; オプションの .astro / .html) | ディスク上のファイル |
| 2 | UIStringExtractor (Babel via ui-string-babel.ts) | MD5ハッシュでキー付けされたセグメント |
| 3 | strings.json | マスターカタログ: { hash: { source, translated, models?, locations? } } |
| 4 | LlmClient.translateUIBatch() | ソース文字列の JSON 配列 → 翻訳 (+ バッチごとのモデル ID) |
| 5 | de.json、pt-BR.json、… | フラットマップ: ソース文字列 → 翻訳 (モデルメタデータなし) |
UIStringExtractor
extractUiCallsFromFileContent は ui-string-babel.ts 内で t("literal") と i18n.t("literal") の呼び出しを検出します。JSファイルとTSファイルは、@babel/parser (モジュールソース、TypeScript、およびJSX) で解析されます。.astro ソースの場合 (ui.uiExtractor.extensions にリストされている場合)、同じ関数がフロントマターとテンプレートの {expression} ブロックを解析し、同じ funcNames ルールを適用します。関数名とファイル拡張子は、ui.uiExtractor を介して設定可能です (ui.reactExtractor はサポートされているエイリアスです)。extract は、追加の入力を同じカタログにマージします。 具体的には、includePackageDescription が有効になっている場合 (デフォルト) のプロジェクトの package.json description、および includeUiLanguageEnglishNames が true の場合のバンドルされたui-languagesマスターカタログ (sourceLocale + targetLocales から構築) からの各 englishName です (ソースですでに検出された文字列が優先されます。languagesManifestPath は読み込まれません)。extract も languagesManifestPath で ui-languages.json を再生成します。セグメントハッシュは、トリミングされたソース文字列の MD5 の最初の8桁の16進数文字 です — これらが strings.json のキーになります。
.html / .htm ソース ( ui.uiExtractor.extensions にリストされている場合) の場合、extract は代わりにファイルを html-i18n-marks.ts 経由でルーティングし、data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label マーカー属性をスキャンします ( ui.uiExtractor.htmlI18nAttributes で設定可能)。ベアマーカーは、要素自身の textContent または属性からソーステキストを取得します。値を持つマーカー ( data-i18n="Key" ) はその値を使用します。data-i18n-locale-src および data-i18n-locale-href はブラウザランタイムのために予約されており、抽出されることはありません。同じモジュールが mark-html コマンドを動かします。このコマンドは、ベアマーカーを自動的に挿入し ( alt および aria-label を含む)、ロケールURLマーカーは挿入しません。HTMLファイルはBabelパスに到達しません。ドキュメント outputDir の下にある生成されたロケールHTMLは、このスキャンから除外されます。
プレーンな Astro SSG サイトでは i18next を省略できます。ビルド時にフラットな {locale}.json を読み込み、ソーステキストのキーで t('source text') を解決します。ソース言語は sourceLocale で、任意の言語を使用できます (examples/astro-website/src/i18n/t.ts と UI 文字列 — Astro ウェブサイト を参照)。
通常のHTMLアプリは、t()の呼び出しの代わりにマーカー属性を使用して、同じカタログモデルに従います — HTMLを翻訳用にマークするを参照してください。すぐに使えるスクリプトはai-i18n-tools/html-runtime/i18n.jsです。
ロケールごとに 1 つのファイルとなる静的 HTML は、このカタログではなくドキュメントパイプライン(translate-docs 内の HtmlTemplateExtractor)です。HTML ページ を参照してください。
strings.json
マスターカタログの構造は以下の通りです。
{
"a1b2c3d4": {
"source": "The English string",
"translated": {
"de": "Der deutsche Text",
"pt-BR": "O texto em português"
},
"models": {
"de": "anthropic/claude-3.5-haiku",
"pt-BR": "openai/gpt-4o"
},
"locations": [{ "file": "src/app/page.tsx", "line": 51 }]
}
}models (オプション) — ロケールごとに、そのロケールの最後に成功したtranslate-ui実行後にどのモデルがその翻訳を生成したか(または、テキストが翻訳ダッシュボードから保存された場合はuser-edited)。locations (オプション) — extractが文字列を見つけた場所(スキャナー + パッケージの説明行;バンドルされたマスターenglishName文字列はlocationsを省略する場合があります)。
extractは新しいキーを追加し、スキャンにまだ存在するキー(スキャナーリテラル、オプションの説明、オプションのバンドルされたマスターenglishName)の既存のtranslated / modelsデータを保持します。translate-uiは欠落しているtranslatedエントリを埋め、翻訳するロケールのmodelsを更新し、フラットなロケールファイルを書き込みます。
ui-languages.json マニフェスト — { code, label, englishName, direction }のJSON配列(BCP-47 code、UI label、参照englishName、"ltr"または"rtl")。sourceLocale + targetLocalesおよびバンドルされたマスターdata/ui-languages-complete.jsonからプロジェクトファイルを構築するには、generate-ui-languagesまたはextractを使用します。
フラットなロケールファイル
各ターゲットロケールには、ソース文字列 → 翻訳(models フィールドなし)をマッピングするフラットなJSONファイル(de.json)が割り当てられます。
{
"The English string": "Der deutsche Text",
"Save": "Speichern"
}i18nextはこれらをリソースバンドルとして読み込み、ソース文字列(キーをデフォルトとするモデル)で翻訳を検索します。
UI 翻訳プロンプト
buildUIPromptMessages は以下の内容を含むシステムおよびユーザー向けメッセージを構築します。
- ソース言語とターゲット言語を特定します(
localeDisplayNamesまたはui-languages.jsonの表示名を使用)。 - ターゲットロケールに期待される書記体系がある場合、スクリプトディレクティブを先頭に付加します(明示的なBCP-47スクリプト、または
hi→ デーヴァナーガリー、ar→ アラビア文字、ja→ 日本語の仮名/漢字などの言語デフォルト)。 - 文字列のJSON配列を送信し、翻訳のJSON配列を返すよう要求します。
- 利用可能な場合は用語集のヒントを含めます。
LlmClient.translateUIBatch は各モデルを順番に試行し、解析エラー、ネットワークエラー、またはスクリプトエラー(ネイティブスクリプトのロケールに対するローマ字/ラテン文字のフォールバックを含む)が発生した場合はフォールバックします。CLIは、ターゲットロケールごとにlocaleModels、オプションのuiModels、およびtranslationModelsからそのリストを構築します(AIモデル)を参照)。
ドキュメントの内部構造
| ステップ | コンポーネント | 結果 |
|---|---|---|
| 1 | Markdown / MDX / JSON / .astro ファイル (translate-docs) | ソースファイル |
| 2 | MarkdownExtractor / JsonExtractor / AstroTemplateExtractor | segments[] — ハッシュ + コンテンツを含む型付きセグメント |
| 3 | PlaceholderHandler | 保護されたテキスト — HTML、アドモニッション、アンカー、MDX、URL、インラインコード、トークンとしてマスクされた強調 |
| 4 | splitTranslatableIntoBatches | batches[] — カウント + 文字数制限でグループ化 |
| 5 | TranslationCache ルックアップ | キャッシュヒット → スキップ; ミス → LlmClient.translateDocumentBatch |
| 6 | PlaceholderHandler.restoreAfterTranslation | 最終テキスト — プレースホルダーが復元されたもの |
| 7 | resolveDocumentationOutputPath | 出力ファイル — Docusaurus レイアウトまたはフラットレイアウト |
エクストラクター
すべてのエクストラクターは BaseExtractor を継承し、extract(content, filepath): Segment[] を実装しています。
MarkdownExtractor- マークダウンを型付きセグメント(frontmatter、heading、paragraph、code、admonition)に分割します。YAML フロントマターは翻訳不可として分類されます(slug、id、およびその他のルーティングキーは変更されません)。トップレベルのexport ...ブロック(React コンポーネント定義など)は、既存のimport ...処理と並行して、翻訳不可のotherセグメントとして分類されます。大文字の JSX タグで始まる複数行ブロック(<Tabs>ブロックなど)は、翻訳可能な段落として分類されます。翻訳不可のセグメント(コードブロック、生の HTML)はそのまま保持されます。AstroTemplateExtractor-.astroマーケティングページの解析と置換(doc-translate.ts内のtranslateAstroFileを介したtranslate-docs)。ユーザー向けの HTML テキストノードと翻訳可能な属性(alt、title、aria-label、placeholder)を抽出し、さらにユーザー向けの場合はテンプレート{expression}ブロック内の文字列リテラルも抽出します。フロントマターの TypeScript、<script>、<style>、保護された属性/キーの値、およびt('…')内のリテラルはスキップします。再構築時に、出力パスが深くなる場合(src/pages/de/index.astroなど)は相対インポートを調整します。Astro ウェブサイトのページ を参照してください。JsonExtractor- Docusaurus の JSON ラベルファイルから文字列値を抽出します(MDX 本文ではなく、Docusaurus UI カタログ)。SvgExtractor- SVG から<text>、<title>、および<desc>のコンテンツを抽出します(translate-docsではなく、translate-svgによってconfig.svg以下のファイルに使用されます)。html-i18n-marks.ts-extractが.html/.htmソースに使用し、mark-htmlコマンドによって使用される、集中型のHTMLタグスキャナー。collectHtmlI18nStrings/collectHtmlI18nLocationsはdata-i18n*マーカー属性(ベアマーカー → 要素のtextContent/title/placeholder、値を持つマーカー → 値)を読み取り、markHtmlContentはベアマーカーをリーフテキスト/タイトル/プレースホルダー要素に挿入します(冪等性があり、data-i18n-ignoreを尊重し、コードのような要素や混合コンテンツ要素はスキップします)。共有のnormalizeI18nTextヘルパーは、ビルド時のキーをブラウザランタイムと同じにします。
Astro ハイブリッドサイト (UI + ページHTML)
プレーンな Astro アプリは、UI 文字列とドキュメントの両方を1つの設定で有効にすることがよくあります(参照: examples/astro-website/)。
| レイヤー | メカニズム | 出力 |
|---|---|---|
| テンプレート HTML | AstroTemplateExtractor + translate-docs | docs[].outputDir 以下のロケールごとの .astro |
フロントマター / t('…') | ui-string-babel.ts + extract + translate-ui | フラットな public/locales/{locale}.json (ソース言語の文字列をキーとする。sourceLocale は任意の言語で可) |
sync コマンドは、有効なステップを順に実行します: extract、次に translate-ui(features.translateUIStrings の場合)→ オプションの translate-svg → translate-docs → オプションの translate-json(--no-ui、--no-svg、--no-docs、または --no-json でスキップされない限り)。初期テンプレート ui-astro-website は UI 文字列のみを足場として提供します。ページ HTML には docs[] と features.translateDocs を追加します。
見出しアンカーの挿入(write-heading-ids CLI)
write-heading-ids コマンドは、ドキュメントの Markdown 用のローカルかつ非LLMな前処理ツールです。実装:src/cli/write-heading-ids.ts がファイルの検出を調整し、src/markdown/write-heading-ids-core.ts が行を解析してアンカーを挿入します。
有効な設定には、少なくとも1つの docs[] ブロックが必要です。各ブロックについて、contentPaths の下にある .md / .mdx ファイルを収集し、プロジェクトの .translate-ignore ルール(ドキュメント翻訳と同じ考え方)を適用し、オプションで --path / --file を使用してサブツリーに制限します。各ファイルは applyHeadingAnchorsToMarkdown で変換されます。コードブロック外のすべてのフラットなATX見出し(# … から ###### … まで)について、任意の形式の既存の見出しIDが選択したスタイルに置き換えられます。HTMLスタイルは、サフィックスのない見出しの上の行に <a id="slug"></a> を書き込みます。--slug-style mdx-comment は見出し行に {/* #slug */} を書き込みます(また、先行するHTMLアンカーを削除します)。スラッグは常に現在の見出しテキストから取得されます。--remove はHTMLアンカー、古典的な {#id} サフィックス、およびMDXコメントIDを削除しますが、新しいものは書き込みません。スラッグアルゴリズムは一般的なエコシステムに一致します — github(デフォルト)、bitbucket、gitlab、pymdown(オプションのUnicode正規化 / パーセントエンコーディングフラグ)、azure-devops、および mdx-comment(githubスラッグ + MDXコメント出力) — そのため、アンカーIDは既存のツール(doctoc、PyMdown、Docusaurusなど)と一貫性を保ちます。--dry-run は書き込まずに編集予定の内容を報告します。
ソースパスの後、同じコマンドがそれらの英語IDを各ロケールの既存の翻訳済みマークダウン(resolveTranslatedOutputPath)に再配置します。翻訳されたタイトルは再スラッグ化されません。見出し途中の{#id} / {/* #id */}は、選択されたスタイルが期待するサフィックス(またはHTMLアンカー)に戻されます。存在しないロケールファイルはスキップされます。
このコマンドは translate-docs や sync 内では実行されません。翻訳または公開前に、ソースファイル内で安定したフラグメントIDを確保したい場合に明示的に実行してください。
プレースホルダー保護
翻訳前に、LLMによる破損を防ぐために、機微な構文が不透明なトークンに置き換えられます。以下の順序で適用されます(復元は逆順):
- フェンスコードブロック(3つ以上のバッククォートまたはチルダ。長いフェンスが短いフェンスを囲む場合を含む) - フェンス全体(情報文字列を含む)は
{{CDF_N}}に置き換えられ、他の構造トークンと順序が保たれます。これにより、::: code-groupや::: tipなどのコンテナ内のサンプルがそのまま保持されます。フェンス情報文字列(VitePressのタブラベル)はソース言語のままです。閉じられていない開始フェンスはテキストとして残され、後続のコンテナクローザーが飲み込まれないようにします。 - 見出しIDサフィックス(ATX見出しの末尾にある従来の
{#id}/ MDX{/* #id */})— 行から完全に取り除かれ、モデルには送信されません。復元後、対応する見出しの末尾に再び付加され、Docusaurusが有効なIDを認識できるようにします。見出し途中のコメントはテキストに残り、後のMDX /{#…}レイヤーで処理されます。マスクされたフェンス内の見出しは取り除かれません。 - HTMLタグとコメント(
<strong>、<!-- ... -->など) - 既知の許可リストにある小文字のHTMLタグは{{HTM_N}}トークンに置き換えられます。大文字のJSXタグ(<Highlight>、<Tabs>、</Tab>)はMDXレイヤー(ステップ6)で個別に処理されます。 - アドモニションマーカー(
:::note、:::) - 開始行のディレクティブプレフィックスのみが{{ADM_OPEN_N}}に置き換えられます。同じ行のタイトルはモデルが翻訳するために残されます。元のテキストと完全に同じ形で復元されます。 - ドキュメントアンカー(HTMLの
<a id="…">、見出しの途中に残ったDocusaurusの{#…}) - そのまま保持されます。 - MDX専用の構文(
src/processors/mdx-placeholders.ts):- MDXコメント(行末の接尾辞ではない見出しの途中の
{/* #my-id */}を含む{/* … */})は{{MDX_N}}に置き換えられます。 - 大文字のJSXタグ(
<Highlight>、<Tabs>、<TabItem>、<TOCInline />、</Highlight>) -{{MDX_N}}として保持され、翻訳可能な文字列属性(label、tooltip、aria-label)は、属性名がdocs[].protectAttributesに含まれていない限り、タグ内で{{JXA_N}}に書き換えられます。<Tabs values={[ { label: '…' } ]}>オブジェクトリテラル内(docs[].protectKeysでスキップ可能)のlabel:と<TabItem value="…">(label属性が存在せず、小文字のスラッグのような値をスキップする場合)も抽出されます。||JXA_N: …||行としてセグメントに追加され、restoreMdxによってマージされて戻されます。 - MDXの波括弧式(
{frontMatter.title}、style={{…}}) - 深さを考慮したマッチングで、{{MDX_N}}に置き換えられます。
- MDXコメント(行末の接尾辞ではない見出しの途中の
- MarkdownのURL(
](url)、src="…") - 翻訳後にマップから復元されます。 - インラインコードスパン(
`code`)と太字で囲まれたインラインコード(**code**) - 保持されます。 - Markdownの強調(オプション、CJK/RTLロケールでは自動的に有効化) - 強調の区切り文字はマスクされます。
モデルが応答を返した後、translate-docsはマップを復元し、セグメントを検証します。同じ二重波括弧トークンの多重集合が存在する必要があり、構造トークン({{HTM_N}}、アドモニションマーカー、{{CDF_N}})はその順序付けられた部分シーケンスを維持する必要があります({{ILC_N}} / {{URL_N}} / {{SE}}などのコンテンツトークンは語順とともに移動する場合があります)。復元されたHTMLタグの種類は、保護されていないソースと一致する必要があり、また、残った二重波括弧の識別子は、ソースに既に存在していたものでなければなりません(したがって、作成されたトークンは失敗します)。ドキュメントのプロンプトはまた、各トークンを1回コピーし、構造トークンの順序を維持し、新しい二重波括弧のラッパーを作成しないようにモデルに要求します。機械的なチェックが引き続き権威を持ちます。
AstroテンプレートとMDX JSXの共有属性/キー保護はsrc/processors/expression-attribute-protection.tsで実装されており、docs[].protectAttributesとdocs[].protectKeysによってブロックごとに駆動されます(protectAttributes / protectKeysを参照)。
キャッシュ (TranslationCache)
SQLiteデータベース (node:sqlite 経由) は、(source_hash, locale) をキーとして translated_text、model、filepath、last_hit_at および関連フィールドを持つ行を格納します。ハッシュは、正規化されたコンテンツ(空白文字を圧縮)のSHA-256の最初の16文字の16進数です。
各実行時、セグメントはハッシュとロケールで検索されます。キャッシュミスのみがLLMに送られます。翻訳後、現在の翻訳スコープ内でヒットしなかったセグメント行に対してlast_hit_atがリセットされます。ドキュメント翻訳中のキャッシュヒットが成功すると、そのセグメントの古いtranslation_failures行がクリアされます。
cleanup は最初に sync --force-update を実行し、その後:
- 古いセグメント行(null
last_hit_at/ 空のファイルパス)を削除します。 - 解決されたソースパスがディスク上に存在しない場合(
doc-block:…、json-block:…、svg-files:…など)、file_trackingキーを削除します。 - メタデータファイルパスが欠落しているファイルを指している翻訳行を削除します。
- 孤立した
translation_failures行を削除します。 - 解決されたソースパスがディスク上に存在しない孤立した
markdown_source_issues行を削除します。 - 設定にないロケール(
sourceLocale、ルートtargetLocales、およびブロックごとのdocs[]/json[]targetLocales)のキャッシュ行を削除します(SQLiteのみ — 生成されたファイルを削除するにはpurge-localeを使用します)。
まずそのパスにバックアップを書き込むことになる--backup <path>が渡されない限り、cache.dbをバックアップしません。
課金対象のモデル呼び出し (採用された翻訳と破棄された再試行) は api_calls に保存されます。呼び出しを記録するコマンドの実行後、UTC暦日で7日を超えた詳細行は月次の api_totals にロールアップされます。usage とダッシュボードの「使用量とコスト」ビューでは、両方のテーブルが統合されます。使用量とコスト を参照してください。
用語集のContextメモとglossary.contextFilesはフィンガープリントされ(prompt_context_hash)、UI、ドキュメント、JSON、SVG、校正プロンプトに注入されます。そのガイダンスを変更すると、次回の実行時に、一致するキャッシュされたセグメントとファイル追跡行が無効になります。ダッシュボードのuser-editedキャッシュ行は保持されます。強制されない行で優先される用語集の翻訳のみを変更した場合、既存のキャッシュは--force / --force-updateまでそのまま維持されます。Forceの行は、保存されたテキストに強制翻訳がまだ含まれていない場合、その用語がソースに含まれるセグメントに対してのみキャッシュミスとなります。また、出力にまだその用語が含まれていないファイルについては、変更されていないファイルのスキップが拒否されます。その行のContextは空のままにします。コンテキストノートは引き続きロケール全体を更新します。Markdownはまた、引用された2〜5語のUIラベル(カタログキーまたはシードされたラベル形状のプレフィックス)を削除する翻訳済みセグメントを拒否します。引用は、太字、インラインコード、見出し、またはそのラベルのみの行です。文中のタイトルケースはヒントであり、翻訳は活用できます(ヒンディー語のCursor accountは、辞書形式のकर्सर खाताではなくकर्सर खातेになる場合があります)。Sign inのような単一コンテンツ語のラベルはヒントのままです。チェックは翻訳における大文字/小文字を無視するため、ソースがそれを引用している場合、文中の小文字のラベルも依然としてカウントされます。同じ単語を使用する通常の散文は、それらを活用する場合があります。シードされたプレフィックスは、共有翻訳がプレースホルダーのない短いフレーズである、大文字で始まるラベルである必要があります。文の語幹はシードされません。そのチェックは次のモデルを再試行し、セグメントを分割しません。
translate-docs コマンドもファイル追跡を使用するため、変更されていないソースで既存の最新の出力がある場合、作業を完全にスキップできます。--check-cache は、期待される書記体系でロケールを再度開くことで、キャッシュされたセグメントが再検証されるようにします。--force-update は、セグメントキャッシュは引き続き使用しながら、すべてのロケールでファイル処理を再実行します。--force は、ファイル追跡をクリアし、API翻訳のためのセグメントキャッシュ読み取りをバイパスします。マークダウンセグメントで試行されたモデルがAST検証に失敗した場合、translate-docs はセグメントを段階的に分割し、より小さな部分で再試行できます(docs[].segmentSplitting.qualityRetrySplit、デフォルトでオン)。同じ品質エラーが3回発生すると、そのモデルリストは早期に終了します。完全なフラグテーブルについては、ドキュメント — キャッシュの動作とフラグを参照してください。
バッチプロンプト形式: translate-docs --prompt-formatは、LlmClient.translateDocumentBatchのみのXML(<seg> / <t>)またはJSON配列/オブジェクトの形式を選択します。抽出、プレースホルダー、検証は変更されません。バッチプロンプト形式を参照してください。
出力パスの解決
resolveDocumentationOutputPath(config, cwd, locale, relPath, kind)はソース相対パスを出力パスにマッピングします:
nestedスタイル (デフォルト): Markdown には{outputDir}/{locale}/{relPath}を使用します。doc-systemスタイル:docsRootの下では、出力は{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}を使用します。docsRoot外のパスはネストされたレイアウトにフォールバックします。エイリアス:docusaurus(デフォルトlocaleSubpath= Docusaurus プラグインパス)、astro-starlight(デフォルトは空のlocaleSubpath)、vitepress(空のdoc-systemと同じlocaleSubpath; BCP-47 フォルダの大文字と小文字を保持)。flatスタイル:{outputDir}/{stem}.{locale}{extension}。flatPreserveRelativeDirがtrueの場合、ソースサブディレクトリはoutputDirの下に保持されます。- カスタム
pathTemplate:{outputDir}、{locale}、{LOCALE}、{relPath}、{stem}、{basename}、{extension}、{docsRoot}、{relativeToDocsRoot}を使用する任意の Markdown レイアウト。 - カスタム
jsonPathTemplate: JSON ラベルファイル用の個別のカスタムレイアウト。同じプレースホルダーを使用。 linkRewriteDocsRootは、翻訳された出力がデフォルトのプロジェクトルート以外に配置される場合に、フラットリンク書き換えツールが正しいプレフィックスを計算できるようにする。
フラットリンクの書き換え
docsOutput.style === "flat"の場合、翻訳されたMarkdownファイルは、ロケールサフィックス付きでソースと並んで配置されます。ページ間の相対リンクは、readme.de.md内の[Guide](./guide.md)がguide.de.mdを指すように書き換えられます。rewriteRelativeLinksによって制御されます(カスタムpathTemplateのないフラットスタイルでは自動的に有効になります)。同じパスは、postProcessing.regexAdjustmentsが実行される前に、Markdown以外のアセットURLにファイルごとの深さのプレフィックスを付加します — Flat link rewriterを参照してください。
JSON の内部構造
| ステップ | コンポーネント | 結果 |
|---|---|---|
| 1 | json[].contentPaths | ファイルが解決されました(ファイル、ディレクトリ、またはグロブ) |
| 2 | NestedJsonExtractor | keyPolicyによって選択された文字列リーフ(ドットパス + ミニマッチ) |
| 3 | PlaceholderHandler + バッチ + TranslationCache | キャッシュヒット → スキップ; ミス → LlmClient.translateDocumentBatch(共有SQLite) |
| 4 | NestedJsonExtractor.reassemble | expandJsonBlockOutputPath(outputPathTemplate)を介した出力ファイル |
NestedJsonExtractor(src/extractors/nested-json-extractor.ts) は任意のネストされた JSON を走査し、翻訳可能な文字列リーフごとに1つのセグメントを出力します。keyPolicy.mode(allowlist、denylist、またはboth) は、ドット表記の minimatch でパスをフィルタリングします(slugのようなベア名は最終キーセグメントに一致します)。- キャッシュファイルの追跡は
file_trackingのjson-block:{blockIndex}:{projectRelPath}を使用します(ドキュメントや SVG と同じcacheDir)。 - Docusaurus
write-translationsカタログ ({ message, description }形式) には使用されません。これらはドキュメント (translate-docs内のdocs[].docusaurusCatalogDir+JsonExtractor) を使用します。 t()UI 文字列には使用されません。UI 文字列 (strings.json+ フラットバンドル) を使用します。- CLI:
translate-json;オーケストレーションはsrc/cli/translate-json-run.ts内。initテンプレート:ui-json-bundles。
共有インフラストラクチャ
LlmClient
Vercel AI SDK (ai + @ai-sdk/openai-compatible) 上に構築された、プロバイダーに依存しないチャットクライアント。アクティブなプロバイダーを provider / providers から解決し、そのプロバイダーの baseUrl + API キー用の OpenAI 互換クライアント (createOpenAICompatible) を構築し、すべての呼び出しを generateText 経由でルーティングします。OpenRouterClient は非推奨のエイリアスとして保持されます。主な動作:
- モデルフォールバック: 解決済みリスト内の各モデルを順番に試行し、リクエストまたは解析の失敗時にフォールバックします。各ターゲットロケールは独自の解決済みチェーンを取得します。設定されている場合は
localeModels(locale)が最初、次にuiModels(UIパイプラインのみ)、そしてtranslationModelsです。ドキュメント、JSON、SVGの翻訳は、非UIチェーンを持つロケールごとのクライアントを作成します。代わりにbench-modelsコマンドは、設定されたIDごとに1つのシングルモデルクライアントを構築し(translationModels、uiModels、およびlocaleModelsの結合。translationModels: [id]、フォールバックなし)、各モデルの時間を計測し、独立して価格設定できるようにします。 - リクエストタイムアウト: アクティブなプロバイダーで
requestTimeout(秒)またはrequestTimeoutMsが指定されている場合、または設定の最上位にある同じキー(デフォルト120秒)が、AbortSignal.timeoutを介して各リクエストを中止します。CLIがcheck-models(任意のプロバイダー)のためにプロバイダーのモデルリストをロードする際、同じ値がGET /modelsに適用されます。未知のモデルIDを破棄するオプションの事前フライトフィルターは、アクティブなプロバイダーがOpenRouterの場合にのみ実行されます。 - OpenRouter追加機能(
openrouterがアクティブな場合のみ):providerリクエストフィールドおよびHTTP-Referer/X-Titleヘッダーを介したスループットルーティング。トークン使用量はすべてのプロバイダーで報告されます。OpenRouterとCheaper Inferenceは、請求されたUSD金額(usage.cost。Cheaper Inferenceはcheaper_inference.billing.billed_cost_usdにフォールバック)も返します。プロバイダーがその金額を省略した場合、USDコストはproviders.<name>.modelPricing、次にプロバイダー全体のpricingデフォルト、次にmodels.devの入力および出力リスト価格から計算され、api_calls行に保存されます。プロバイダーが報告したコスト(0を含む)は決して置き換えられません。不明なコストは未設定のままです。呼び出しの価格設定は<cacheDir>/benchmark-scores.jsonのmodels.devスライスのみを読み取り、languagebenchやArenaファイルをダウンロードしません。 - デバッグトラフィックログ:
debugTrafficFilePathが設定されている場合、リクエストとレスポンスのJSONをファイルに追記します(プログラムによる)。CLI--debug-failedは、失敗したUI、ドキュメント、JSON、SVGの翻訳チェック試行について、システム/ユーザープロンプト、生のアシスタント応答、および検証エラーを含むFAILED-TRANSLATIONファイルをcacheDirの下に書き込みます。プロバイダーAPI / 空のボディの失敗は、プロンプトのみのファイルをダンプする代わりにコンソールに表示されます。
suggest-models とダッシュボードの「モデル」タブはLLMを呼び出しません。これらは、languagebench ChrFとLMArena Arena Scoreから得られる品質インデックスを用いて、アクティブなプロバイダーのチャットカタログをランク付けします。価格は、100万トークンあたりのUSDレートを3:1の割合でブレンドしたものです(カタログ、次にmodels.dev、次にlanguagebench)。--quality はインデックスでソートし、--price は品質と価格のパレートフロンティアをたどります。これらはオプションで providers.<name>.translationModels を置き換えます。集計は <cacheDir>/benchmark-scores.json に格納されています。AIモデル および suggest-models を参照してください。
設定の読み込み
loadI18nConfigFromFile(configPath, cwd)パイプライン:
ai-i18n-tools.config.json(JSON) を読み取って解析します。mergeWithDefaults-defaultI18nConfigPartialとディープマージし、docs[].sourceFilesエントリをcontentPathsにマージします。expandTargetLocalesFileReferenceInRawInput-targetLocalesを配列に強制変換し、パスのようなエントリを拒否します(ui-languages.jsonへのパスではなく、BCP-47コードである必要があります);languagesManifestPathはmergeWithDefaults中に{ui.flatOutputDir}/ui-languages.jsonにデフォルト設定されます。expandDocumentationTargetLocalesInRawInput- 各docs[].targetLocalesエントリについても同様です。expandJsonTargetLocalesInRawInput- 各json[].targetLocalesエントリで同じです。parseI18nConfig- Zod 検証 +validateI18nBusinessRules。applyProviderOverrideToRawInput- CLI で-P/--providerが渡された場合。applyEnvOverrides-OPENROUTER_BASE_URL、OLLAMA_BASE_URL、I18N_SOURCE_LOCALE、およびI18N_TARGET_LOCALESが設定されている場合に適用します (API キーはLlmClient内でプロバイダーごとに個別に解決されます)。augmentConfigWithUiLanguagesMaster- バンドルされたマスターカタログからマニフェスト表示名を添付します。assertEffectiveLocalesInUiLanguagesMaster- 該当する場合、マスターカタログに対してロケールコードを検証します。
initはinitConfigTemplatesからスターター設定を書き込みます: ui-markdown (UI文字列とフラットなREADMEブロック)、docs-markdown (READMEとMarkdownのみ)、ui-docusaurus、ui-starlight、ui-vitepress (VitePressドキュメント + vitepressThemeCatalog)、ui-nextra (Nextraドキュメント + nextraDictionaryPath)、ui-astro-website (プレーンなAstro UI。.astroページの翻訳にはdocs[]を追加)、ui-json-bundles (JSON json[]のみ)、ui-python、ui-python-gettext、ui-python-django、ui-python-flask。--with-readmeは、README.mdをまだリストしていないテンプレートに同じREADMEブロックを追加し、translateDocsをオンにします。詳細はUI文字列 — 初期化、READMEとMarkdownドキュメントにi18nを追加する、Pythonアプリケーションを参照してください。
ロガー
Loggerは、ANSIカラー出力でdebug、info、warn、errorレベルをサポートします。詳細モード(-v)ではdebugが有効になります。logFilePathが設定されている場合、ログ行はそのファイルにも書き込まれます。
自己ローカライズ(ツールUI)
このツールは、CLIヘルプ、トラフィックの多いログ/サマリー/エラーメッセージ、および翻訳ダッシュボードといった自身のUIを、ユーザーのために翻訳するコンテンツとは別にローカライズします。
- ロケール解決 (
resolveUiLocale内のsrc/core/ui-locale.ts):-L/--ui-lang>AI_I18N_LANG> 設定のuiLanguage> ホストOSのロケール (Intl.DateTimeFormat().resolvedOptions().locale) からUIロケールを選択します。候補は正規化され、出荷されたバンドルセットと完全に一致するか、最も近いバリエーション(例:pt-PT→pt-BR、en-US→en-GB)で照合され、ソースロケール(en-GB)にフォールバックします。CLIは、ヘルプが構築される前(argvの事前解析スキャン)に一度解決され、設定の読み込み後に再度解決されるため、uiLanguageが適用されます(ただし、フラグと環境変数が優先されます)。 - ランタイム (
src/i18n/index.ts):{{name}}補間付きの最小限のt(source, vars)で、src/i18n/locales/<code>.json内のフラットなロケールごとのバンドルに対して英語のソース文字列をキーとしています(ビルド時にdist/i18n/localesにコピーされます)。キーまたはバンドルが見つからない場合は、ソーステキストが返されます。これはUI文字列と同じキーをデフォルトとするモデルであり、ハッシュルックアップはありません。 - ダッシュボード: サーバーは、解決されたUIロケールに対して
{ locale, dir, bundle }を返すGET /api/ui-i18nを公開します。フロントエンドは<html lang>/dirを設定し、data-i18n*属性を介して静的マークアップをローカライズします。 - ドッグフーディング: バンドルは
pnpm i18n:self(sync-ui --ui-block src/i18n/strings.json) によって生成されます。これはai-i18n-tools.config.json内のCLIおよびダッシュボードのuiブロックを抽出し、翻訳します。カタログキーは、src/cli/とsrc/i18n/全体でのt()呼び出しと、src/dashboard-app/index.html内のダッシュボードのdata-i18n*マーカーから取得されます。
拡張ポイント
カスタム関数名(UI抽出)
設定を通じて非標準の翻訳関数名を追加します。
{
"ui": {
"uiExtractor": {
"funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
"extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
"htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
}
}
}(ui.reactExtractorはui.uiExtractorの完全にサポートされたエイリアスです。)
.html / .htmをextensionsに追加して、extract中にHTMLマーカー属性をスキャンします。ui.uiExtractor.htmlI18nAttributesはオプションで、デフォルトは["data-i18n", "data-i18n-title", "data-i18n-placeholder"]です。data-i18nは要素のtextContentにマッピングされ、data-i18n-<attr>はその属性の値にマッピングされます(例:data-i18n-aria-label)。
カスタムエクストラクタ
パッケージから ContentExtractor を実装します。
import { BaseExtractor, type Segment } from 'ai-i18n-tools';
class MyExtractor extends BaseExtractor {
readonly name = 'my-format';
canHandle(filepath: string) { return filepath.endsWith('.myext'); }
extract(content: string, filepath: string): Segment[] { /* … */ }
reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}'ai-i18n-tools' からエクスポートされたパブリックエクストラクタクラスを拡張して、カスタムエクストラクタを登録します (例: MarkdownExtractor をサブクラス化します)。CLI は組み込みエクストラクタを内部的に接続します。doc-translate.ts のディープインポートはサポートされていません。
カスタム出力パス
任意のファイルレイアウトには docsOutput.pathTemplate を使用します
{
"docs": [
{
"docsOutput": {
"pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
}
}
]
}ソースツリー
完全な src/ レイアウト (ファイルレベルの参照)
src/
├── index.ts Public API re-exports
│
├── cli/
│ ├── index.ts CLI entry point (commander)
│ ├── extract-strings.ts `extract` command implementation
│ ├── mark-html.ts `mark-html` command (insert bare `data-i18n*` markers into HTML)
│ ├── translate-ui-strings.ts `translate-ui` command implementation
│ ├── doc-translate.ts `translate-docs` command (documentation files only)
│ ├── translate-json-run.ts `translate-json` command (`json[]` nested locale bundles)
│ ├── translate-svg.ts `translate-svg` command (SVG files from `config.svg`)
│ ├── write-heading-ids.ts `write-heading-ids` command (markdown heading anchors)
│ ├── bench-models.ts `bench-models` command (per-model translate latency/token/cost benchmark)
│ ├── helpers.ts Shared CLI utilities
│ └── file-utils.ts File collection helpers
│
├── markdown/
│ └── write-heading-ids-core.ts Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│ ├── types.ts Zod schemas + TypeScript types for all config shapes
│ ├── config.ts Config loading, merging, validation, init templates
│ ├── cache.ts SQLite translation cache (node:sqlite)
│ ├── prompt-builder.ts LLM prompt construction for docs and UI strings
│ ├── output-paths.ts Docusaurus / flat output path resolution
│ ├── ui-languages.ts ui-languages.json loading and locale resolution
│ ├── ui-locale.ts Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│ ├── locale-utils.ts BCP-47 normalisation, locale list parsing, script/Han-variant validation
│ └── errors.ts Typed error classes
│
├── extractors/
│ ├── base-extractor.ts Abstract base class for all extractors
│ ├── ui-string-extractor.ts JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│ ├── ui-string-babel.ts Babel `t()` discovery (`extractUiCallsFromFileContent`)
│ ├── ui-string-locations.ts Source locations for extracted UI strings
│ ├── html-i18n-marks.ts HTML `data-i18n*` marker scanner + `mark-html` annotator
│ ├── classify-segment.ts Heuristic segment type classification
│ ├── markdown-extractor.ts Markdown / MDX segment extraction
│ ├── markdown-segment-split.ts Optional segment splitting for long markdown blocks
│ ├── frontmatter-fields.ts Selective YAML front matter field translation
│ ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│ ├── json-extractor.ts Docusaurus catalog JSON extraction (`translate-docs`)
│ ├── nested-json-extractor.ts Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│ └── svg-extractor.ts SVG text extraction
│
├── processors/
│ ├── placeholder-handler.ts Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│ ├── expression-attribute-protection.ts Shared protected attribute/key lists (Astro + MDX JSX)
│ ├── url-placeholders.ts Markdown URL protection/restore
│ ├── admonition-placeholders.ts Docusaurus admonition protection/restore
│ ├── anchor-placeholders.ts HTML anchor / heading ID protection/restore
│ ├── html-tag-placeholders.ts Lowercase HTML tag / comment protection ({{HTM_N}})
│ ├── placeholder-integrity.ts Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│ ├── mdx-placeholders.ts MDX comments, JSX tags, brace expressions, JSX attribute extraction
│ ├── batch-processor.ts Segment → batch grouping (count + char limits)
│ ├── validator.ts Post-translation structural checks
│ └── flat-link-rewrite.ts Relative link rewriting for flat output
│
├── api/
│ ├── llm-client.ts LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│ └── provider-models-catalog.ts Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│ ├── glossary.ts Glossary loading (CSV + auto-build from strings.json)
│ ├── matcher.ts Term hint extraction for prompts
│ └── translation-context.ts contextFiles loader and guidance fingerprints
│
├── runtime/
│ ├── index.ts Runtime re-exports
│ ├── template.ts interpolateTemplate, flipUiArrowsForRtl
│ ├── ui-language-display.ts getUILanguageLabel, getUILanguageLabelNative
│ └── i18next-helpers.ts RTL detection, i18next setup factories
│
├── i18n/ Self-localisation runtime for the tool's own UI
│ ├── index.ts t(source, vars) + bundle/manifest loaders (keyed by English source string)
│ └── locales/ Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│ ├── index.html Translation Dashboard static UI (HTML/CSS/JS)
│ ├── app.js
│ └── styles.css
│
├── server/
│ └── translation-dashboard.ts Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
├── logger.ts Leveled logger with ANSI support
├── hash.ts Segment hash (SHA-256 first 16 hex)
├── table.ts Display-width aware table rendering (CJK/emoji column alignment)
├── load-dotenv.ts Load `.env` / `.env.local` beside the config when no API key is set
└── ignore-parser.ts .translate-ignore file parser