Skip to content

Astro ウェブサイト ​

静的な Astro のマーケティングサイトまたはアプリサイト (Starlight ではなく、プレーンな Astro) では、Astro の組み込み i18n ルーティング と ai-i18n-tools を組み合わせます。Astro インテグレーション も参照してください。

リファレンス実装は examples/astro-website です(その README も参照)。英語は /、9 つのターゲットロケールは /{locale}/(de、fr、es、ar、ja、ko、zh-cn、zh-tw、pt-br)です。

ハイブリッドパイプライン ​

ほとんどのチームは2つのパイプラインのハイブリッドを使用しています(これらは競合しません):

パイプライン使用対象コマンド出力
ページ HTMLテンプレート本体の見出し、段落、ナビゲーションラベル、インライン配列translate-docsロケールごとに src/pages/{locale}/index.astro
UI 文字列 (t())Frontmatter データ、スクリーンショットのタブ ラベル、共有配列extract → translate-uipublic/locales/{locale}.json (ソース言語の文字列をキーとして使用)

言語を追加または削除するときは、3 つのリストを同期させてください。targetLocales(ai-i18n-tools.config.json 内)、i18n.locales(astro.config.mjs 内、Astro は 小文字のルートコード(例: pt-br)を使用)、および ui-languages.json(generate-ui-languages 経由)。フラットバンドルの ファイル名は設定のケース(pt-BR.json)を使用します。Astro の pt-br ルートをマニフェストの code フィールド経由でそのファイルにマッピングします(examples/astro-website/src/i18n/locale.ts を参照)。

リファレンスプロジェクトからの package.json スクリプトの例:

json
{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:translate-ui": "ai-i18n-tools translate-ui",
  "i18n:translate": "ai-i18n-tools translate-docs",
  "i18n:locales": "ai-i18n-tools generate-ui-languages",
  "i18n:sync": "ai-i18n-tools sync"
}

UI文字列 (SSG) ​

UI抽出のひな形をinit -t ui-astro-website -P ollamaで作成し、ページHTMLも翻訳する場合はdocs[]ブロックにマージします(ページの解析と置換を参照)。リポジトリのREADMEも翻訳します: init -t ui-astro-website -P ollama --with-readme。(READMEとMarkdownドキュメントにi18nを追加するを参照)。コピーはTypeScriptモジュールではt('…')で、.astroフロントマターでは囲みます(重複するロケールページよりもUI文字列を優先する場合は、テンプレートの{expression}ブロックも)。ページHTMLはt()を必要としません。translate-docsがそれをコピーします。JS/TSプロンプトは、i18nextのインストールとブートストラップを除き、これらのフロントマターおよびデータファイルに適用されます。Astroはi18nextではなく、ビルド時にmakeTでtを解決します。

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

astro.config.mjs の i18n.defaultLocale に一致するように sourceLocale を設定します。Astro がビルド時にインポートできるディレクトリにフラット バンドルを書き込みます (テンプレートでは public/locales/ を使用します)。ソース言語のリテラルをキーとして参照することで、ビルド時に t('…') を解決します (examples/astro-website/src/i18n/t.ts を参照。strings.json は抽出キャッシュであり、ランタイム バンドルではありません)。その言語は sourceLocale であり、任意の言語にすることができます。この例では英語を使用しています。静的サイトでは ai-i18n-tools/runtime や i18next は必要ありません。ただし、読み込み後に言語を切り替えるクライアント アイランドを追加する場合は除きます。

t() を呼び出すすべてのページ (ソース ロケールのページと各 src/pages/{locale}/ のコピー) を接続します:

astro
import { loadFlatBundle, makeT } from '../i18n/t';        // or ../../i18n/t in locale subfolders
import { resolvePageLocale, useTranslations } from '../i18n/utils';

const locale = resolvePageLocale(Astro.currentLocale);
const flat = await loadFlatBundle(Astro.currentLocale);
const t = useTranslations(locale, makeT(flat));

例におけるサポートヘルパー: ラベル、方向、BCP-47コード用の src/i18n/utils.ts, src/i18n/locale.ts, ui-languages.json。targetLocales を変更した後、generate-ui-languages を実行します(オプションで languagesManifestPath を設定し、マニフェストをヘルパーと同じ場所に配置します。例: src/i18n/ui-languages.json)。MainLayout.astro は resolveUiLanguage(Astro.currentLocale) から <html lang> と <html dir> を設定します。LanguagePicker.astro は astro:i18n から getRelativeLocaleUrl を使用します。

ページ (解析と置換) ​

.astro ファイル内のハードコードされた HTML を含むマーケティングページでは、translate-docs にテキストノードおよび属性(alt、title、aria-label、placeholder)の抽出をさせ、ドキュメントキャッシュで翻訳し、ページツリー内にロケール固有のコピーを書き出します。ほとんどの表示用コピーでは、t() は不要です。

構造的な属性とキーの値は、デフォルトでは翻訳されません。組み込みの保護機能は、class、id、style、src、href、data-*、およびほとんどの aria-* などの JSX/HTML 属性、さらにテンプレートの {expression} ブロック内の class、key、id などのオブジェクトキーをカバーします。カスタム属性(例: Tailwind の variant または CMS の slug フィールド)を使用する場合は、docs[].protectAttributes と docs[].protectKeys を使用してこれらのリストを拡張します。同じオプションは、マークダウン翻訳中の MDX JSX にも適用されます(protectAttributes / protectKeys を参照)。

features.translateDocsを有効化し、docs[]ブロックを追加します。例:

json
{
  "features": { "translateDocs": true },
  "docs": [{
    "contentPaths": ["src/pages/index.astro"],
    "outputDir": "src/pages",
    "docsOutput": {
      "style": "astro-starlight",
      "docsRoot": "src/pages"
    },
    "addFrontmatter": false
  }]
}

ai-i18n-tools translate-docs (または examples/astro-website の pnpm i18n:translate) を実行します。ソース ページは src/pages/index.astro のままです (この例では英語ですが、sourceLocale は任意の言語にできます)。各ターゲット ロケールは src/pages/{locale}/index.astro を取得し、追加のディレクトリ レベルに合わせてインポートが調整されます (例: ../layouts/ → ../../layouts/)。

テンプレートの本文内では、{expression} ブロック内の文字列リテラル (インライン配列、オブジェクトの title/desc フィールド) は、ユーザーに表示される場合に翻訳されます。保護された属性/キーの引用符で囲まれた値、t('…')、<script>、<style> 内のリテラルは変更されません。このパスでは Frontmatter の TypeScript は翻訳されません。共有 frontmatter (t() のインポートとデータ配列を含む) は、英語ページとロケール ページで同一に保つか、英語ページを編集した後に translate-docs を再実行して、ロケールのコピーが frontmatter の変更を反映するようにします。frontmatter のみのコピーには、代わりに UI 文字列パイプライン を使用してください。

完全なハイブリッドランディングページ(HTML は translate-docs 経由、スクリーンショットのタブラベルは t() + translate-ui 経由)については、examples/astro-website を参照してください。

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