国際化（i18n）

Starlightは、ルーティング、フォールバックコンテンツ、右横書き（right-to-left、RTL）言語へのフルサポートなど、複数言語サイトを構築するための機能を組み込みで提供します。

i18nの設定

localesとdefaultLocaleをStarlightインテグレーションに渡すことで、サポートする言語についてStarlightに伝えます。

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      // このサイトのデフォルト言語として英語を設定します。
      defaultLocale: 'en',
      locales: {
        // 英語のドキュメントは`src/content/docs/en/`に置きます。
        en: {
          label: 'English',
        },
        // 簡体字中国語のドキュメントは`src/content/docs/zh-cn/`に置きます。
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // アラビア語のドキュメントは`src/content/docs/ar/`に置きます。
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
      },
    }),
  ],
});

defaultLocaleはフォールバックコンテンツとUIラベルに使用されるため、コンテンツを最初に書く可能性が最も高い言語、またはすでにコンテンツがある言語を選択してください。

src/content/docs/に各言語のディレクトリを作成します。たとえば上で示した構成に対しては、以下のフォルダを作成します。
- ディレクトリsrc/
  - ディレクトリcontent/
    ディレクトリdocs/
    ディレクトリar/
    …
    ディレクトリen/
    …
    ディレクトリzh-cn/
    …
これで各言語のディレクトリにコンテンツ用のファイルを追加できるようになりました。言語間でページを関連付けるために、同じページには同じファイル名を使用してください。フォールバックコンテンツや翻訳に関する通知など、Starlightのi18n機能をフル活用しましょう。

たとえば、ar/index.mdとen/index.mdは、アラビア語版と英語版のホームページをそれぞれ表わします。

ルートロケールを使用する

「ルート」ロケールを使用すると、パスにi18nプレフィックスを付けずにある言語を提供できます。たとえば英語をルートロケールとすると、英語のページパスは/en/aboutではなく/aboutのようになります。

ルートロケールを設定するには、localesのrootキーを使用します。ルートロケールがコンテンツのデフォルトロケールでもある場合は、defaultLocaleを削除するか、'root'に設定します。

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'root', // 任意
      locales: {
        root: {
          label: 'English',
          lang: 'en', // langはルートロケールに必要です
        },
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

rootロケールを使用する場合は、言語専用のフォルダではなく、src/content/docs/にその言語のページを直接保存します。たとえば上記の設定を使用した場合、英語と中国語のホームページ用ファイルは次のようになります。

ディレクトリsrc/
- ディレクトリcontent/
  - ディレクトリdocs/
    index.md
    ディレクトリzh-cn/
    index.md

単一言語のサイト

デフォルトでは、Starlightは単一言語（英語）のサイトです。他の言語で単一言語のサイトを作成するには、その言語をlocalesにおいてrootに設定します。

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

export default defineConfig({
  integrations: [
    starlight({
      title: '私のドキュメント',
      locales: {
        root: {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

これにより、言語選択機能などの他の国際化機能は有効化せずに、Starlightのデフォルト言語を上書きできます。

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

Starlightは、すべての言語で同等のページが作成されることを想定しています。たとえばen/about.mdファイルがある場合、サポートする他の言語でもそれぞれabout.mdを作成してください。これにより、まだ翻訳されていないページに対して、Starlightが自動的にフォールバックコンテンツを提供できるようになります。

ある言語の翻訳がまだである場合、Starlightはそのページのコンテンツを（defaultLocaleで設定する）デフォルト言語で表示します。たとえば、概要（about）ページのフランス語版をまだ作成していない場合、デフォルト言語が英語であれば、/fr/aboutを訪れた人には未翻訳であるという通知とともに英語のコンテンツが表示されます。これにより、まずデフォルト言語にコンテンツを追加し、そして翻訳者が時間を掛けて徐々に翻訳していくことが可能となります。

StarlightのUIを翻訳する

Starlightでは、読者が選択した言語でサイト全体を体験できるように、翻訳されたコンテンツファイルをホストするだけでなく、デフォルトUIの文字列（たとえば目次に表示されている「目次」という見出し）も翻訳できるようになっています。

アラビア語、イタリア語、インドネシア語、ウクライナ語、オランダ語、カタロニア語、ガリシア語、スウェーデン語、スペイン語、スロバキア語、チェコ語、デンマーク語、ドイツ語、トルコ語、ノルウェー語(ブークモール)、ヒンディー語、フランス語、ベトナム語、ヘブライ語、ペルシア語、ポーランド語、ポルトガル語、ルーマニア語、ロシア語、英語、韓国語、中国語、中国語 (台湾)、日本語の翻訳済みUI文字列がすでに用意されていますが、デフォルト言語をさらに追加するための貢献も歓迎します。

18nデータコレクションを使用すると、サポートしたい言語の翻訳を追加したり、デフォルトのラベルを上書きしたりできます。

設定がまだであれば、src/content/config.tsでi18nデータコレクションを設定します。

import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};

UI文字列を追加で翻訳したいロケールごとに、src/content/i18n/にJSONファイルを作成します。たとえば、以下ではアラビア語と簡体字中国語の翻訳ファイルを追加しています。
- ディレクトリsrc/
  - ディレクトリcontent/
    ディレクトリi18n/
    ar.json
    zh-CN.json

翻訳したいキーに対応する翻訳を、JSONファイルに追加します。キーは英語のままとし、値のみを翻訳します（例: "search.label": "Buscar"）。

以下は、Starlightが英語版のデフォルトとして使用している文字列です。

{
  "skipLink.label": "Skip to content",
  "search.label": "Search",
  "search.ctrlKey": "Ctrl",
  "search.cancelLabel": "Cancel",
  "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
  "themeSelect.accessibleLabel": "Select theme",
  "themeSelect.dark": "Dark",
  "themeSelect.light": "Light",
  "themeSelect.auto": "Auto",
  "languageSelect.accessibleLabel": "Select language",
  "menuButton.accessibleLabel": "Menu",
  "sidebarNav.accessibleLabel": "Main",
  "tableOfContents.onThisPage": "On this page",
  "tableOfContents.overview": "Overview",
  "i18n.untranslatedContent": "This content is not available in your language yet.",
  "page.editLink": "Edit page",
  "page.lastUpdated": "Last updated:",
  "page.previousLink": "Previous",
  "page.nextLink": "Next",
  "page.draft": "This content is a draft and will not be included in production builds.",
  "404.text": "Page not found. Check the URL or try using the search bar.",
  "aside.note": "Note",
  "aside.tip": "Tip",
  "aside.caution": "Caution",
  "aside.danger": "Danger",
  "fileTree.directory": "Directory",
  "builtWithStarlight.label": "Built with Starlight"
}

Starlightのコードブロックは、Expressive Codeライブラリによって動作しています。expressiveCodeキーを使用して、同じJSONファイルでUI文字列の翻訳について設定できます。

{
  "expressiveCode.copyButtonCopied": "Copied!",
  "expressiveCode.copyButtonTooltip": "Copy to clipboard",
  "expressiveCode.terminalWindowFallbackTitle": "Terminal window"
}

Starlightの検索モーダルは、Pagefindライブラリによって動作しています。PagefindのUIの翻訳は、pagefindキーを使用して同じJSONファイルに設定できます。

{
  "pagefind.clear_search": "Clear",
  "pagefind.load_more": "Load more results",
  "pagefind.search_label": "Search this site",
  "pagefind.filters_label": "Filters",
  "pagefind.zero_results": "No results for [SEARCH_TERM]",
  "pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
  "pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
  "pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
  "pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
  "pagefind.searching": "Searching for [SEARCH_TERM]..."
}

翻訳スキーマを拡張する

i18nSchema()オプションのextendを設定することで、サイトの翻訳辞書にカスタムキーを追加できます。以下の例では、オプションのcustom.labelキーが新たにデフォルトのキーに追加されています。

import { defineCollection, z } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({
    type: 'data',
    schema: i18nSchema({
      extend: z.object({
        'custom.label': z.string().optional(),
      }),
    }),
  }),
};

コンテンツコレクションのスキーマについて詳しくは、Astroドキュメントの「コレクションスキーマの定義」を参照してください。