Astro連携
ai-i18n-toolsをAstroで利用するには、一般的な2つのセットアップがあります。Astro Starlightドキュメントサイトと、プレーンなAstroマーケティングサイトまたはアプリサイトです。どちらもページコンテンツにはDocuments (translate-docs)を使用します。プレーンなAstroサイトでは、フロントマターや共有データ内のt()文字列にUI文字列 (extract / translate-ui)を組み合わせて使用することがよくあります。
関連情報: UI 文字列、ドキュメント、および以下の実行可能なサンプル。
Astro Starlight
Astro Starlight のドキュメントサイトには init -t ui-starlight と docsOutput.style: "astro-starlight" を使用します。このプリセットは、localeSubpath が空の doc-system のエイリアスです。翻訳されたページは、ソースロケールのツリーの横にある src/content/docs/<locale>/ の下に配置されます。sourceLocale には任意の言語を指定できます。
クイックスタート
ai-i18n-tools init -t ui-starlight -P cheaperinference
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync # or: ai-i18n-tools sync
pnpm dev # Starlight dev server (project-specific script)ページレイアウト
英語のMarkdownとMDXはStarlightのコンテンツルート(通常はsrc/content/docs/)にあります。翻訳されたコピーはソースツリーの横に書き込まれます。
src/content/docs/quick-start.md → src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx → src/content/docs/fr/guide/setup.mdxdocs[] ブロックを1つ設定します:
{
"contentPaths": ["src/content/docs/"],
"outputDir": "src/content/docs",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/content/docs"
}
}contentPaths には、sourceLocale で書かれた .md / .mdx のファイルとディレクトリを指定します。その言語には任意の言語を指定できます。docsRoot には、Starlight がコンテンツルートとして使用するのと同じフォルダーを設定します。
Starlight UIのオーバーライドは、必要に応じて別のdocs[]ブロックでsrc/content/i18n/en.jsonをjsonPathTemplateとともに使用できます。詳細については、ドキュメント — ドキュメントの初期化を参照してください。
Starlightは多くのロケール向けに組み込みのUI文字列(ナビゲーションラベル、検索プレースホルダー、目次など)を提供しています。別のシェル/テーマパイプラインを設定する必要はありません。ページコンテンツにはtranslate-docsのみを使用してください。他のフレームワークについては、フレームワークのシェル翻訳を参照してください。
明示的なサイドバーの label、サイトの title、および astro.config.mjs 内の social[].label は、このツールが翻訳しない英語のリテラルです。ページの翻訳された frontmatter (title) からラベルが取得されるように、slug エントリを使用することを推奨します。独自の文言が必要なグループや外部リンクでは、Starlight のロケールごとの translations マップを使用します (デフォルトロケールでは label、その他のロケールでは translations['pt-BR'])。現在の Starlight スキーマでは social[].label には translations フィールドがないため、記述されたままになります。slug エントリを使用している Starlight sidebar および examples/astro-docs/astro.config.mjs を参照してください。
既存のサイトで i18n を有効にする
初回セットアップは、ウェブサイトまたはドキュメントサイトにi18nを追加するのプロンプトを使用します。以下のチェックリストは、手作業による同じ作業です。
- Starlight の設定で
localesを指定します。英語をプレフィックスなしにする (labelと必須のlang) 場合は、rootエントリを含めます。 - デフォルト言語がそのルートロケールである場合は
defaultLocale: 'root'を設定します。Starlight のデフォルトがすでに一致している場合にのみdefaultLocaleを省略します。 - 英語のページは
src/content/docs/に残ります。translate-docsはsrc/content/docs/<locale>/を書き込みます。 targetLocalesを非ルートロケールのキーに合わせます (注意: Starlight のディレクトリキーはpt-brのように、多くの場合小文字です)。
プロジェクト例
examples/astro-docs — 英語ソースはsrc/content/docs/、コミットされた翻訳はsrc/content/docs/<locale>/、RTLロケール (ar)、および用語集駆動型翻訳。pnpm devをポート3050で実行します。
プレーンなAstro (マーケティングおよびアプリサイト)
静的なAstroマーケティングサイトまたはアプリサイト(Starlightではない)の場合、Astro組み込みのi18nルーティングとai-i18n-toolsを組み合わせます。初回セットアップは、ウェブサイトまたはドキュメントサイトにi18nを追加するのプロンプトを使用します。リファレンス実装はexamples/astro-websiteです。英語は/、ターゲットロケールは/{locale}/にあります。
ほとんどのチームは、同じページで2つのパイプラインのハイブリッドを使用します。
| パイプライン | 使用対象 | コマンド | 出力 |
|---|---|---|---|
| ページ HTML | テンプレート本体の見出し、段落、ナビゲーションラベル、インライン配列 | translate-docs | ロケールごとに src/pages/{locale}/index.astro |
UI 文字列 (t()) | Frontmatter データ、タブのラベル、共有配列 | extract → translate-ui | public/locales/{locale}.json (キーとしてソース言語の文字列を使用) |
クイックスタート
ai-i18n-tools init -t ui-astro-website -P ollama
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm devinit -t ui-astro-website -P ollama を使用してUI抽出の足場を構築し、ページHTMLも翻訳する際にはdocs[] ブロックにマージします。
{
"features": {
"translateUIStrings": true,
"translateDocs": true
},
"ui": {
"sourceRoots": ["src/"],
"stringsJson": "public/locales/strings.json",
"flatOutputDir": "public/locales/"
},
"docs": [{
"contentPaths": ["src/pages/index.astro"],
"outputDir": "src/pages",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/pages"
},
"addFrontmatter": false
}]
}言語を追加または削除する際には、3つのリストを揃えてください。ai-i18n-tools.config.json内のtargetLocales、astro.config.mjs内のi18n.locales(Astroはpt-brのような小文字のルートコードを使用します)、およびui-languages.json(generate-ui-languages経由)。フラットバンドルのファイル名は設定のケース(pt-BR.json)を使用します。Astroのpt-brルートをマニフェストのcodeフィールド経由でそのファイルにマッピングします。
ビルド時に、ソース言語のリテラルをキーとしてルックアップすることで t('…') を解決します (examples/astro-website/src/i18n/t.ts を参照)。sourceLocale には任意の言語を指定できます。この例では英語を使用しています。静的サイトの場合、ロード後に言語を切り替えるクライアントアイランドを追加しない限り、ai-i18n-tools/runtime や i18next は必要ありません。
プロジェクト例
examples/astro-website — translate-docs経由のHTMLとt() + translate-ui経由のスクリーンショットタブラベルを備えたハイブリッドランディングページ。
プロジェクト例
| プロジェクト | ユースケース | ポート |
|---|---|---|
| examples/astro-docs | Starlightドキュメント | 3050 |
| examples/astro-website | プレーンなAstroマーケティングサイト(HTML + t()ハイブリッド) | (READMEを参照) |
examples/astro-docsとexamples/docusaurus-docsを比較してください — チュートリアルの内容は似ていますが、StarlightではなくDocusaurusの出力スタイルを採用しています。