ai-i18n-tools

Appearance

クイックスタート ​

デフォルトのinitテンプレート（ui-markdown）は、UIの抽出と翻訳のみを有効にします。ui-docusaurus、ui-starlight、ui-vitepress、ui-nextra、およびui-fumadocsテンプレートは、ドキュメントの翻訳（translate-docs）を有効にします。ui-vitepressはVitePressテーマ文字列用のdocsOutput.vitepressThemeCatalogも足場を固め、ui-nextraはNextraテーマ辞書用のdocs[].nextraDictionaryPathを足場を固め（サイドバーの_meta.tsは自動的に収集されます）、ui-fumadocsはFumadocs UIオーバーライド用のdocsOutput.fumadocsUiCatalogを足場を固めます（サイドバーのmeta.jsonは自動的に収集されます）。ui-astro-websiteテンプレートは、プレーンなAstroアプリ（.astroファイルを含む）のUI抽出を足場を固めます。.astroページのHTMLのtranslate-docsも必要な場合は、docs[]ブロックを追加します（Astroウェブサイトページ（解析と置換）を参照）。リファレンスexamples/astro-websiteは、両方のパイプラインを使用します。設定に従って、抽出、UI翻訳、オプションのSVGファイル翻訳、およびドキュメント翻訳を実行する1つのコマンドが必要な場合は、syncを使用します。

実行可能な例 ​

9つの実行可能なプロジェクトとフィクスチャは、examples/にあります。例カタログ（コンソールアプリ、Next.js + Docusaurus、Astroウェブサイト、Astro Starlightドキュメント、VitePressドキュメント、Nextraドキュメント、Fumadocsドキュメント、マルチプロバイダー比較、マークダウンストレステスト）を参照してください。

1つの例をスタンドアロンで実行します（モノレポ全体をクローンせずに）：

bash
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync    # example scripts call the locally installed CLI

console-appは任意のサンプルフォルダー名に置き換えてください。各サンプルは現在のパッケージバージョンに一致する公開済みのキャレット範囲 ai-i18n-tools を宣言し、npmからCLIをインストールします。サンプルごとのREADMEには、フォルダー名を埋めた同じスニペットが記載されています。

完全な ai-i18n-tools リポジトリから — degit で単一のサンプルフォルダーではなくリポジトリ全体をクローンした場合:

bash
pnpm install          # repository root
pnpm run build        # after changing CLI source
cd examples/console-app
pnpm run i18n:sync    # preferred — uses the workspace-linked CLI
# or: ai-i18n-tools sync   # after PATH setup — see Using the CLI

ワークスペースのoverridesエントリー(ai-i18n-tools: workspace:*)は、ワークスペースのサンプルをローカルのチェックアウトに自動的にリンクします。スタンドアロンのフィクスチャ(multi-provider、test-markdown)はワークスペースパッケージではありません。これらのフォルダーからは node ../../bin/ai-i18n-tools.mjs … を使用してください。リポジトリルート(このパッケージ自身のdocs/i18n)からCLIを実行するには、direnv allowの後に単独の ai-i18n-tools を使用するか、pnpm i18n:sync / node bin/ai-i18n-tools.mjs … を使用してください。インストール — クローンしたモノレポおよび開発ガイドを参照してください。

プロバイダーと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>を渡さない場合はopenrouter）。プリセットの切り替え、プロバイダの追加、またはモデルリストの調整については、LLMプロバイダとモデルを参照してください。
  2. 環境またはプロジェクトルートの.envファイル内にある対応するAPIキー。各組み込みプリセットは、プリセットテーブルから指定された環境変数を読み取ります（例えば、デフォルトではOPENROUTER_API_KEY、または-P anthropicでスキャフォールドする場合はANTHROPIC_API_KEY）。例外はOllamaです。ローカルエンドポイントを使用するため、キーは不要です。インストール — プロバイダAPIキーの設定を参照してください。

extract、status、およびLLMを呼び出さないその他のコマンドは、プロバイダーやAPIキーを必要としません。

コア CLI コマンド ​

ai-i18n-toolsをインストールし、ベアコマンド用にシェルを設定した後、プロジェクトルートから実行します。以下の例ではai-i18n-toolsを直接使用しています。

bash
# Set the API key for your active provider (see preset table; skip for local Ollama)
# Default init uses openrouter:
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Or scaffold another preset at init, e.g. anthropic:
# export ANTHROPIC_API_KEY=sk-ant-your-key-here

# UI strings (default template enables extract + translate-ui)
ai-i18n-tools init [-P <provider>]    # default: openrouter
ai-i18n-tools init -P anthropic
ai-i18n-tools extract
ai-i18n-tools translate-ui

# Documents (Docusaurus-oriented template)
ai-i18n-tools init -t ui-docusaurus [-P <provider>]
ai-i18n-tools init -t ui-docusaurus -P openai
# Astro Starlight docs: ai-i18n-tools init -t ui-starlight [-P <provider>]
# VitePress docs: ai-i18n-tools init -t ui-vitepress [-P <provider>]
# Nextra docs: ai-i18n-tools init -t ui-nextra [-P <provider>]
# Fumadocs docs: ai-i18n-tools init -t ui-fumadocs [-P <provider>]
# Plain Astro website UI: ai-i18n-tools init -t ui-astro-website [-P <provider>]
ai-i18n-tools translate-docs

# JSON (no t() in source)
ai-i18n-tools init -t ui-json-bundles [-P <provider>]
ai-i18n-tools translate-json

# Combined: extract UI strings, then translate UI + SVG + docs + json[] (per config features)
ai-i18n-tools sync

# Translation status (UI strings per locale; markdown per file × locale in chunked tables)
ai-i18n-tools status
# ai-i18n-tools status --max-columns 12   # wider tables, fewer chunks

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

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

好ましい sync は、「translate-uiを実行し、その後translate-svg、次にtranslate-docs、最後にtranslate-jsonを実行する」ことが必要だったすべてのことに対してです：ai-i18n-tools syncは、あなたの設定に従って、extract（有効な場合）、translate-ui、オプションのtranslate-svg、translate-docs、その後オプションのtranslate-jsonを、正しい順序で共有フラグとともに実行します。手動でこれらのステップを連鎖させるのは、順序、抽出、ロケールフラグを間違えるのが簡単です。i18n:translate:ui、i18n:translate:svg、i18n:translate:docs、およびi18n:translate:jsonは、単一のステップが孤立して必要な場合にのみ使用してください。

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"
}

ヒント: CLI出力やダッシュボードを別の言語で表示したい場合は、-L <code> を渡すか AI_I18N_LANG を設定してください — ツールUIの言語 を参照してください。

結合された同期 ​

UI 文字列とドキュメントを一緒に実行するには、すべての機能を単一の設定で有効にします。

UIとドキュメントの設定を統合した例
json
{
  "sourceLocale": "en-GB",
  "targetLocales": ["de", "fr", "es", "pt-BR", "ja", "ko", "zh-Hans"],
  "features": {
    "translateUIStrings": true,
    "translateDocs": true,
    "translateSVG": false
  },
  "glossary": {
    "uiGlossary": "src/locales/strings.json",
    "userGlossary": "glossary-user.csv"
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "src/locales/strings.json",
    "flatOutputDir": "src/locales/"
  },
  "cacheDir": ".translation-cache",
  "docs": [
    {
      "contentPaths": ["docs/"],
      "outputDir": "i18n/",
      "docsOutput": { "style": "flat" }
    }
  ]
}

glossary.uiGlossaryはドキュメント翻訳にUIと同じstrings.jsonカタログを指定して用語の一貫性を保ち、glossary.userGlossaryは製品用語に対するCSVオーバーライドを追加します。詳細は用語集を参照してください。

1つのパイプラインを実行するにはai-i18n-tools syncを実行します。features.translateUIStringsが有効な場合は、extractした後、translate UI文字列を処理します。任意でtranslate SVG（features.translateSVG + svgブロック）、translate documentation（設定に従ってdocs[]）、その後任意でtranslate-json（features.translateJson + json[]）を実行します。--no-ui、--no-svg、--no-docs、または--no-jsonで該当部分をスキップします。ドキュメントおよびjson[]の各ステップは--dry-run、-p / --path、--force、--force-update、--check-cacheを受け付けます（--no-docsの場合はドキュメント専用フラグが無視され、--no-jsonが未設定の場合はJSONが同じキャッシュフラグを使用します）。

ブロックに対してdocs[].targetLocalesを使用すると、そのブロックのファイルをUIよりも少ないロケール数に翻訳できます（有効なドキュメントロケールはブロック間の和集合になります）：

json
{
  "targetLocales": ["de", "fr", "es", "pt-BR", "ja", "ko", "zh-Hans"],
  "docs": [
    {
      "contentPaths": ["docs/"],
      "outputDir": "i18n/",
      "targetLocales": ["de", "fr", "es"]
    }
  ]
}

混合ドキュメント設定 (docsOutput.style = "docusaurus" + "flat") ​

設定ファイル内で docs に複数のエントリを追加することで、同じ設定で複数のドキュメントパイプラインを組み合わせることができます。これは、Docusaurusサイト（docsOutput.style = "docusaurus"）とルートレベルのMarkdownファイル（たとえば、ロケール接尾辞付きファイル名で翻訳すべきリポジトリのREADME（docsOutput.style = "flat"））を併せ持つプロジェクトでよく見られる構成です。

DocusaurusとフラットなREADME設定を組み合わせた例
json
{
  "sourceLocale": "en-GB",
  "targetLocales": ["ar", "es", "fr", "de", "pt-BR"],
  "features": {
    "translateUIStrings": true,
    "translateDocs": true
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "locales/strings.json",
    "flatOutputDir": "public/locales/"
  },
  "cacheDir": ".translation-cache",
  "docs": [
    {
      "description": "Docusaurus site content (markdown)",
      "contentPaths": ["docs-site/docs/"],
      "outputDir": "docs-site/i18n",
      "docusaurusCatalogDir": "docs-site/i18n/en",
      "addFrontmatter": true,
      "docsOutput": {
        "style": "docusaurus",
        "docsRoot": "docs-site/docs"
      }
    },
    {
      "description": "Root README with docsOutput.style flat",
      "contentPaths": ["README.md"],
      "outputDir": "translated-docs",
      "addFrontmatter": false,
      "docsOutput": {
        "style": "flat",
        "postProcessing": {
          "languageListBlock": {
            "start": "<small id=\"lang-list\">",
            "end": "</small>",
            "separator": " · ",
            "label": "local"
          }
        }
      }
    }
  ]
}

ai-i18n-tools sync でこれを実行する方法:

  • UI文字列は src/ から public/locales/ へ抽出／翻訳されます。
  • 最初のドキュメントブロックは、docs-site/docs/ から docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current/ へMarkdownを翻訳します（ローカライズされたドキュメントページ）。
  • docs[].docusaurusCatalogDir を設定し、features.translateDocs を有効にすると、同じブロックが docs-site/i18n/en/ 配下の各ターゲットロケールフォルダーにDocusaurusシェルJSONも翻訳します（ナビゲーションバー、フッター、テーマ／プラグインカタログなど。MDX本文は対象外）。
  • 2番目のドキュメントブロックは、README.md を translated-docs/ 配下のロケール接尾辞付きファイルに翻訳します（docsOutput.style = "flat"）。
  • すべてのドキュメントブロックは cacheDir を共有するため、変更されていないセグメントは実行間で再利用され、API 呼び出し回数とコストを削減します。

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

Copyright © Waldemar Scudeller Jr.