国際化（i18n）

ドキュメントに多言語サポートを追加する

zudo-docはzfbのi18nルーティングを使用して複数の言語をサポートしています。

仕組み

• 英語（デフォルト）： /docs/... — コンテンツはsrc/content/docs/に格納

• 日本語： /ja/docs/... — コンテンツはsrc/content/docs-ja/に格納

サイトヘッダーの言語切り替えで、ユーザーは利用可能な言語を切り替えることができます。

設定ベースのロケール構成

ロケールはsrc/config/settings.tsで設定します：

export const settings = {
  // ...
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
};

各ロケールエントリに対して、zudo-docは自動的に：

• zfbコンテンツコレクション（docs-{code}）を作成

• zfbのi18nルーティングにロケールを登録

• 適切なページルートを生成

• 言語切り替えにロケールを追加

つまり、新しいロケールの追加には設定エントリとコンテンツディレクトリのみが必要です — コレクションやルートの手動セットアップは不要です。

ディレクトリ構造

ローカライズされたドキュメントは英語のディレクトリ構造をミラーします：

src/content/
├── docs/
│   ├── getting-started/
│   │   ├── introduction.mdx
│   │   └── installation.mdx
│   └── guides/
│       └── configuration.mdx
└── docs-ja/
    ├── getting-started/
    │   ├── introduction.mdx
    │   └── installation.mdx
    └── guides/
        └── configuration.mdx

言語切り替え

言語切り替えはヘッダーの右端に表示されます。現在の言語コード（ENまたはJA）と、別の言語に切り替えるためのリンクが表示されます。切り替えは/ja/プレフィックスの追加または削除により、代替URLを自動的に計算します。

UI翻訳キー

zudo-docは組み込みUI文字列に翻訳キーシステムを使用しています。キーは名前空間ごとに整理されています：

• nav.* — ヘッダーナビゲーションラベル（例：nav.gettingStarted、nav.guides）

• toc.* — 目次のラベル

• search.* — 検索ダイアログのテキスト

• code.* — コードブロックのUI（コピーボタンなど）

• doc.* — ドキュメントレベルのUI（編集リンク、メタデータラベルなど）

これらのキーにより、コンテンツだけでなくUI全体をすべての設定済み言語でローカライズできます。

zfb設定

ロケールリストはzfb.config.tsを経由します。settings.localesの各エントリは自動的にdocs-{code}コンテンツコレクションになります — 別途維持するi18nブロックはありません。pages/[locale]/docs/[...slug].tsx配下のページルートがpaths()エクスポートでロケールを列挙するため、英語ページは言語プレフィックスなし（/docs/...）で配信され、デフォルト以外のロケールはコードをプレフィックスとして使用します（/ja/docs/...）。

新しい言語の追加

新しい言語（例：韓国語）を追加するには：

1. settings.tsにロケールを追加：

   locales: {
     ja: { label: "JA", dir: "src/content/docs-ja" },
     ko: { label: "KO", dir: "src/content/docs-ko" },
   },

2. コンテンツディレクトリを作成：src/content/docs-ko/

3. 英語のディレクトリ構造をミラーして翻訳ファイルを配置

4. 新しいロケール用のUI翻訳を追加

defaultLocale

defaultLocaleはURLプレフィックスなしで配信されるロケールを指定します。デフォルトは"en"で、zfbのデフォルトロケールルーティングに使用するキーと一致している必要があります：

export const settings = {
  // ...
  defaultLocale: "en" as const,
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
};

zfb.config.tsで設定されたprefixDefaultLocale: falseにより、デフォルトロケールはパスに言語コードを含まない/docs/...で配信され、他のすべてのロケールはキーをプレフィックスとして使用します（日本語の場合は/ja/docs/...）。defaultLocaleを変更する場合は、zfb.config.ts内の対応するルーティングとコレクションの設定も更新する必要があります。

Default-locale-only prefixes

一部のコンテンツはデフォルトロケールでのみ提供されるよう意図的に設計されています。これらのルートはデフォルトロケール専用プレフィックスと呼ばれ、src/config/settings.tsのdefaultLocaleOnlyPrefixes設定で管理されます：

export const settings = {
  // ...
  defaultLocaleOnlyPrefixes: [
    "/docs/claude-md/",
    "/docs/claude-skills/",
    "/docs/claude-agents/",
    "/docs/claude-commands/",
  ] as string[],
};

意味するところ

これらのプレフィックスのいずれかで始まるURLを持つページは、デフォルトロケール（英語）のみに存在します。言語切り替えはこれらのページに対して別ロケールへのリンクを表示しません。また、docs-ja/配下にこれらのページの日本語ミラーファイルを作成すべきではありません。

現在のエントリ

上記の4つのプレフィックスは、プロジェクトの.claude/ディレクトリにあるClaude設定ファイル（CLAUDE.md、スキル、エージェント、コマンド）を表示する自動生成ページ（Claudeリソースセクション）をカバーしています。ソース素材（Claude設定ファイル）は翻訳されていないため、これらは英語専用となっています。

ルーターによる適用方法

pages/[locale]/docs/[[...slug]].tsxのページルートは、paths()エクスポート内で各スラッグをdefaultLocaleOnlyPrefixesと照合します。再構築されたURLがプレフィックスと一致する場合、そのパスはデフォルト以外のロケールのパスリストから除外されるため、/ja/docs/claude-md/...のようなルートは生成されません。

独自プレフィックスの追加

英語専用にしたいセクション（例：自動生成されたAPIリファレンスページ）がある場合は、配列にURLプレフィックスを追加します：

defaultLocaleOnlyPrefixes: [
  "/docs/claude-md/",
  "/docs/claude-skills/",
  "/docs/claude-agents/",
  "/docs/claude-commands/",
  "/docs/api-reference/", // 追加するプレフィックス
] as string[],

プレフィックスが以下の条件を満たしていることを確認してください：

• /docs/（またはコンテンツディレクトリに対応するパス）で始まる

• 末尾にスラッシュがある

• バイリンガルで保持したいプレフィックスと重複しない