国際化（i18n）

ガイドi18n
On this page

国際化（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.json で各ロケールに表示ラベルを付与します（右から左へ記述する言語には方向も）:

{
	"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 文字列はまだロケールごとに翻訳されていません。 自身のページコンテンツの読書体験は完全に翻訳されますが、周囲のテーマの 装備はまだです。
  • RTL レイアウトのミラーリングはベースライン。 dir="rtl" は正しく設定されますが、 一部の装飾的な詳細（Admonition のアクセントバーの側面など）はまだ反転しません。
  • 自動翻訳なし。 docs/i18n/<code>/ の各ファイルは他の Markdown ページと同様に 手作業で作成します。

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

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

SEO

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

Edit this page Download Markdown Last updated Aug 23, 2026, 2:17:28 AM