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-ui | public/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 スクリプトの例:
{
"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を解決します。
ai-i18n-tools init -t ui-astro-website -P ollama
ai-i18n-tools extract
ai-i18n-tools translate-uiastro.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}/ のコピー) を接続します:
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[]ブロックを追加します。例:
{
"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 を参照してください。