Copy

国際化（i18n）

このページの内容

ロケールの追加
ビルドされる内容
未翻訳のページ
言語スイッチャー
バージョンとロケールを組み合わせたドキュメント
テーマのクローム（UI 文字列）
現在対象外の機能
カスタムアイコンとインクルード
SEO

国際化（i18n）

ドキュメントを他の言語に翻訳し、それぞれが独自の URL プレフィックス、独自の <html lang dir>、および自動言語スイッチャーを持ちます。プラグインも個別のビルドステップも不要です。

ロケールの追加

翻訳済みコンテンツは docs/i18n/<code>/ に置き、通常の docs/ ツリーとページごとに対応させます:

docs/
├── index.md
├── guides/
│   └── setup.md
└── i18n/
    ├── es/
    │   ├── index.md
    │   └── guides/
    │       └── setup.md
    └── ar/
        └── index.md

<code> はフォルダ名とビルド URL プレフィックスの両方になります（docs/i18n/es/guides/setup.md → /es/guides/setup/）。短く保ってください - 裸の言語コード（es、fr）または言語-地域ペア（pt-BR、zh-Hans）はどちらも使用できます（文字/数字/ハイフンのみ）。通常の docs/ ツリーは常にデフォルトロケールで、サイトルートにプレフィックスなしでビルドされます。 docs/i18n/ を追加しても変更はありません。

bxsites.yaml で各ロケールに表示ラベルを付与します（右から左へ記述する言語には方向も）:

i18n:
  defaultLocale: { code: en, label: English }
  locales:
    - { code: es, label: Español }
    - { code: ar, label: العربية, dir: rtl }
    - { code: pt-BR, label: "Português (Brasil)", flag: 🇧🇷 }

{
	"i18n": {
		"defaultLocale": { "code": "en", "label": "English" },
		"locales": [
			{ "code": "es", "label": "Español" },
			{ "code": "ar", "label": "العربية", "dir": "rtl" },
			{ "code": "pt-BR", "label": "Português (Brasil)", "flag": "🇧🇷" }
		]
	}
}

defaultLocale はデフォルトロケールが英語でない場合のみ設定が必要です。 locales はそれ以外のすべてのリストです。docs/i18n/<code>/ フォルダは存在するだけで自動的にビルドされます。locales は表示ラベルとテキスト方向を提供するだけのメタデータです。

flag はオプションです。スイッチャーは約 40 の一般的な言語コードに対して独自にフラグ絵文字を選択します（地域コード pt-BR を先にチェックし、次に基底言語 pt にフォールバック）。組み込みのルックアップが認識しないコードに対してのみ flag を設定してください（その場合は 🌐 にフォールバックします）。

ビルドされる内容

各ロケールは独立した完全なビルドです。独自の search-index.json、独自の assets/、通常のビルドが生成するすべてのものが site/<code>/ （site/es/、site/ar/）に書き出されます。ロケールごとに有効化する設定はありません: docs/i18n/es/ が存在するだけで、bxSites build が自動的に拾います。

未翻訳のページ

ロケールが使用可能になる前にすべてのページを翻訳する必要はありません。 docs/i18n/es/ にないページも期待される URL でビルドされます。デフォルトロケールのコンテンツが表示され、ページの上部に「このページはまだ翻訳されていません」という小さな通知が表示されます。404 になることも、翻訳進行中に半壊に見えることもありません。

各ロケールのナビゲーションは常にデフォルトロケールのものと同じ形状です。言語スイッチャーが機能するのもこのためです: 言語を切り替えると、そのロケールのホームページではなく、同じページ（翻訳済みかどうかに関わらず）に移動します。

言語スイッチャー

複数のロケールが存在すると、すべてのテーマがヘッダーに自動的にフラグアイコンの言語ドロップダウンをレンダリングします。オプトインは不要です。バージョンスイッチャーと同様です。現在のロケールのフラグをトリガーとして表示し、開くとすべてのロケールが自身のフラグとラベルとともに一覧表示され、現在のものがアクティブとしてマークされます。現在ビルドしていないロケールを選ぶと、それはまったくレンダリングされません。

バージョンとロケールを組み合わせたドキュメント

バージョンとロケールは 1 段階だけ組み合わせられます: バージョン自身のページの隣に docs/versions/<name>/i18n/<code>/ フォルダを置くと、トップレベルの docs/i18n/<code>/ がまさに docs/ 自体をミラーするのとまったく同じ方法で、そのバージョン自身の構造をミラーします:

docs/
  versions/
    2.0/
      index.md
      guides/
        setup.md
      i18n/
        es/
          index.md          # 翻訳済み
          guides/
            setup.md        # 未翻訳のページはトップレベルの i18n と同様にフォールバックします

これにより site/versions/2.0/es/ がビルドされます。バージョン自身のデフォルトロケールページ（site/versions/2.0/）も言語スイッチャーを持ちますが、そこには そのバージョン自身が翻訳を持つロケールだけが一覧表示されます - 独自の i18n/ サブフォルダを持たないバージョンは、この機能が存在する以前とまったく同じようにレンダリングされ、スイッチャーは表示されません。バージョンを切り替えると常にそのバージョン自身のデフォルトロケールに戻り（対象バージョンが同じ翻訳を持っているとは想定しません）、ロケールを切り替えると常に現在のバージョンに留まります。

テーマのクローム（UI 文字列）

各組み込みテーマを取り囲む UI テキスト全体 - 検索プレースホルダー、「このページの内容」、「このページを編集」、「最終更新」、404 ページ、タグページのタイトル、そして「まだ翻訳されていません」という通知自体も、自分のページコンテンツだけでなく、ロケールごとに翻訳されるようになりました。

4 つのロケールには標準で組み込みの翻訳が付属しています: de、es、it、 ja。これらのロケールコードのいずれかをビルドすると、設定不要で自動的に完全に翻訳されたテーマクロームが得られます。それ以外のロケールコード（または表現を変えたいページ）は英語にフォールバックします - bxsites.yaml のそのロケール自身のエントリに独自の strings を追加して、気になるキーだけを上書きしてください:

i18n:
  defaultLocale: { code: en, label: English }
  locales:
    - code: fr
      label: Français
      strings:
        searchPlaceholder: Rechercher dans la documentation...
        onThisPage: Sur cette page
    - code: es
      label: Español
      strings: { toggleDarkMode: Cambiar a modo nocturno }

{
	"i18n": {
		"defaultLocale": { "code": "en", "label": "English" },
		"locales": [
			{
				"code": "fr",
				"label": "Français",
				"strings": {
					"searchPlaceholder": "Rechercher dans la documentation...",
					"onThisPage": "Sur cette page"
				}
			},
			{
				"code": "es",
				"label": "Español",
				"strings": { "toggleDarkMode": "Cambiar a modo nocturno" }
			}
		]
	}
}

（es のような）組み込み翻訳を持つロケールでも、同じ方法で個々のキーを上書きできます - 自分自身の strings は、組み込み翻訳にも英語のデフォルト値にも常に優先されます。defaultLocale 自身も独自の strings を持つことができ、デフォルトロケールが英語ではなく、英語のデフォルト値にフォールバックする代わりに独自のクローム表現を使いたいプロジェクトのために使えます。

上書き可能なキーの全リスト: searchPlaceholder、searchAriaLabel、 searchNoResults、toggleDarkMode、toggleNavigation、toggleSection （プレースホルダー {title}）、repository、version、language （プレースホルダー {label}）、onThisPage、editThisPage、 downloadMarkdown、lastUpdated、notTranslatedNotice （プレースホルダー {locale}）、notFoundTitle、notFoundBody、 tagsTitle、そして pageNavigation。

現在対象外の機能

ブログのクロームは英語のまま。 ブログサブシステム自身の UI 文字列（「Categories」、「Archive」、「Read more」、「N min read」など）は、上記の strings オーバーライドではまだカバーされていません - カバーされるのはテーマクロームの残りの部分のみです。
lastUpdated 自身の日付の値はロケールに対応していません。 ラベルは翻訳されますが、日付/時刻の値自体はロケールに関係なく同じ形式のままフォーマットされます。
RTL レイアウトのミラーリングはベースライン。 dir="rtl" は正しく設定されますが、一部の装飾的な詳細（Admonition のアクセントバーの側面など）はまだ反転しません。
自動翻訳なし。 docs/i18n/<code>/ の各ファイルは他の Markdown ページと同様に手作業で作成します。

カスタムアイコンとインクルード

custom: アイコン参照と ::: include はどちらも、ビルドされているロケールに関係なく、プロジェクト独自の docs/assets/ に対して解決されます。これらは共有アセットであり、翻訳者がロケールごとに複製する必要はありません。

SEO

各ロケールのページは、バージョン管理されたページと同じように、デフォルトロケールのページと一緒に sitemap.xml と llms.txt に含まれます。

このページを編集 Markdownをダウンロード最終更新 Aug 28, 2026, 3:16:38 AM