Astro Starlightを国際化(i18n)機能で複数言語に対応する

2025/03/16

AstroのドキュメントテンプレートStarlightを使って、複数言語に対応したので備忘録を残します。

Starlightのi18n機能

Starlightには、以下のような国際化（i18n）機能が組み込まれています。

複数言語のルーティング
フォールバックコンテンツ
右横書き（RTL）言語のフルサポート

これらの機能により、効率的に多言語サイトを構築できます。

i18nの設定方法

astro.config.mjsファイルで、サポートする言語を指定します。

デフォルトの言語(localesに入っている言語以外に対応するための言語)も設定しましょう。

私の場合は、英語（en）と日本語（ja）をサポートし、デフォルトの言語を日本語に設定しました。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
    integrations: [
        starlight({
            title: 'My Docs',
            defaultLocale: 'ja',
            locales: {
                en: {
                    label: 'English',
                },
                ja: {
                    label: '日本語',
                },
                // 他の言語を追加
            },
        }),
    ],
});

src/content/docs/に各言語のディレクトリを作成します：
- ディレクトリsrc/
  - ディレクトリcontent/
    …
  - ディレクトリdocs/
    ディレクトリen/
    …
    ディレクトリja/
    …
    … 他の言語ディレクトリ

各言語ディレクトリに、対応するコンテンツファイル(記事)を配置します。

同じページには同じファイル名を使用することで、言語間でページを関連付けられます。

特定の言語をパスにプレフィックスを付けずに提供したい場合、ルートロケールを設定できます。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
    integrations: [
        starlight({
            defaultLocale: 'root',
            locales: {
                root: {
                    label: '日本語',
                    lang: 'ja',
                },
                en: {
                    label: 'English',
                    lang: 'en',
                },
            },
        });
    ],
});

この場合、日本語のコンテンツはsrc/content/docs/直下に配置します。

ディレクトリsrc/
- ディレクトリcontent/
  - …
- ディレクトリdocs/
  - index.md (日本語のindex.md)
  - ディレクトリen/
    index.md

フォールバックコンテンツ

未翻訳のページがある場合、Starlightは自動的にデフォルト言語のコンテンツを表示し、未翻訳である旨を通知します。

これにより、コンテンツを段階的に翻訳していくことが可能になります。

UIの翻訳

StarlightのデフォルトのUI文字列も翻訳できます。src/content/i18n/に各言語のJSONファイルを作成し、翻訳を追加します。

{
  "search.label": "検索",
  "tableOfContents.onThisPage": "目次",
  // 他の翻訳キー
}

詳しくは、Starlightのドキュメントを参照してください。