--- title: 国際化（i18n） order: 8 tags: [ガイド, i18n] --- # 国際化（i18n） ドキュメントを他の言語に翻訳し、それぞれが独自の URL プレフィックス、 独自の ``、および自動言語スイッチャーを持ちます。 プラグインも個別のビルドステップも不要です。 ## ロケールの追加 翻訳済みコンテンツは `docs/i18n//` に置き、通常の `docs/` ツリーと ページごとに対応させます: ``` docs/ ├── index.md ├── guides/ │ └── setup.md └── i18n/ ├── es/ │ ├── index.md │ └── guides/ │ └── setup.md └── ar/ └── index.md ``` `` はフォルダ名とビルド URL プレフィックスの両方になります （`docs/i18n/es/guides/setup.md` → `/es/guides/setup/`）。 短く保ってください - 裸の言語コード（`es`、`fr`）または言語-地域ペア （`pt-BR`、`zh-Hans`）はどちらも使用できます（文字/数字/ハイフンのみ）。 通常の `docs/` ツリーは常に**デフォルトロケール**で、サイトルートにプレフィックスなしでビルドされます。 `docs/i18n/` を追加しても変更はありません。 `bxsites.json` で各ロケールに表示ラベルを付与します（右から左へ記述する言語には方向も）: ```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//` フォルダは 存在するだけで自動的にビルドされます。`locales` は表示ラベルとテキスト方向を提供するだけのメタデータです。 `flag` はオプションです。スイッチャーは約 40 の一般的な言語コードに対して 独自にフラグ絵文字を選択します（地域コード `pt-BR` を先にチェックし、次に基底言語 `pt` にフォールバック）。 組み込みのルックアップが認識しないコードに対してのみ `flag` を設定してください（その場合は 🌐 にフォールバックします）。 ## ビルドされる内容 各ロケールは独立した完全なビルドです。独自の `search-index.json`、 独自の `assets/`、通常のビルドが生成するすべてのものが `site//` （`site/es/`、`site/ar/`）に書き出されます。ロケールごとに有効化する設定はありません: `docs/i18n/es/` が存在するだけで、`bxSites build` が自動的に拾います。 ## 未翻訳のページ ロケールが使用可能になる前にすべてのページを翻訳する必要はありません。 `docs/i18n/es/` にないページも期待される URL でビルドされます。 デフォルトロケールのコンテンツが表示され、ページの上部に「このページはまだ翻訳されていません」という 小さな通知が表示されます。404 になることも、翻訳進行中に半壊に見えることもありません。 各ロケールのナビゲーションは常にデフォルトロケールのものと同じ形状です。 言語スイッチャーが機能するのもこのためです: 言語を切り替えると、 そのロケールのホームページではなく、*同じページ*（翻訳済みかどうかに関わらず）に移動します。 ## 言語スイッチャー 複数のロケールが存在すると、すべてのテーマがヘッダーに自動的にフラグアイコンの 言語ドロップダウンをレンダリングします。オプトインは不要です。バージョンスイッチャーと同様です。 現在のロケールのフラグをトリガーとして表示し、開くとすべてのロケールが自身の フラグとラベルとともに一覧表示され、現在のものがアクティブとしてマークされます。 現在ビルドしていないロケールを選ぶと、それはまったくレンダリングされません。 ## バージョンとロケールを組み合わせたドキュメント バージョンとロケールは 1 段階だけ組み合わせられます: バージョン自身のページの 隣に `docs/versions//i18n//` フォルダを置くと、トップレベルの `docs/i18n//` がまさに `docs/` 自体をミラーするのとまったく同じ方法で、 そのバージョン自身の構造をミラーします: ```text title="docs/versions/2.0/ layout" 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//` の各ファイルは他の Markdown ページと同様に 手作業で作成します。 ## カスタムアイコンとインクルード `custom:` アイコン参照と `::: include` はどちらも、ビルドされているロケールに関係なく、 プロジェクト独自の `docs/assets/` に対して解決されます。これらは共有アセットであり、 翻訳者がロケールごとに複製する必要はありません。 ## SEO 各ロケールのページは、バージョン管理されたページと同じように、デフォルトロケールのページと一緒に `sitemap.xml` と `llms.txt` に含まれます。