国際化

ロケール対応のルーティング、言語ごとのナビゲーション、翻訳された UI、SEO を備え、複数の言語でドキュメントを配信できます — すべて規約優先で。

Blume は 1 つのプロジェクトを多言語で配信します。翻訳したファイルを適切な場所に置くだけで、Blume がルーティング、言語スイッチャー、ロケールごとのナビゲーション、SEO を自動的に設定します — 別途メンテナンスすべきルーティングレイヤーはありません。オプトイン方式なので、i18n ブロックがなければサイトはこれまでどおり単一言語のままです。

有効にする

ロケールの一覧とどれをデフォルトにするかを指定した i18n ブロックを追加します:

i18n: {
  defaultLocale: "en",
  locales: [
    { code: "en", label: "English" },
    { code: "fr", label: "Français" },
    { code: "ar", label: "العربية", dir: "rtl" },
  ],
}

各ロケールは code(URL で使用)、label(言語スイッチャーに表示)、そして右から左に記述するスクリプト用の任意の dir(既定は "ltr")を持ちます。任意の style は、blume translate にそのロケール向けの自由記述のガイダンス — 文体、方言、用語法、たとえば "Brazilian Portuguese, informal você" — を与えます。これにより、その選択はエージェント任せになるのではなく、最初の翻訳の時点から固定されます。

翻訳コンテンツを整理する

デフォルトロケールはコンテンツルートに置きます。その他のロケールはすべて、code を名前とするトップレベルのフォルダーとして、デフォルトの構造をミラーリングします:

docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar

翻訳したいファイルだけを翻訳すれば十分です — それ以外は自動的にフォールバックします(フォールバックを参照)。

ファイル名のサフィックス

翻訳を元のファイルの隣に置いておきたいですか? parser: "dot" を設定すれば、フォルダーを使う代わりにロケールのサフィックス付きのファイル名を使えます:

docs/
  guides/quickstart.mdx     ->  /guides/quickstart      (default)
  guides/quickstart.fr.mdx  ->  /fr/guides/quickstart   (French)

部分的な翻訳に適しています — ツリー全体をミラーリングせずに、翻訳済みの数ページだけを同じ場所に配置できます。

共有ファイル

変更履歴やステータスページのように、どの言語でも内容が同じコンテンツには $ マーカーを付けると、1 つのファイルを重複なくすべてのロケールで使えます:

docs/changelog.$.mdx   ->  /changelog and /fr/changelog (same content)
docs/guides/meta.$.ts   (folder meta applied to every locale)

ロケール固有の meta.ts は、その言語について共有版を引き続き上書きします。

デフォルトロケールの URL

既定では、デフォルトロケールには URL プレフィックスが付かず(/、/guides/quickstart)、他のロケールにはプレフィックスが付きます(/fr/…)。これにより主要言語の URL がすっきりと保たれます。デフォルトを含むすべてのロケールにプレフィックスを付けるには:

i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}

ロケールごとのナビゲーション

各言語はそのロケールのファイルから構築された独自のサイドバーを持つため、翻訳ごとに構造、並び順、ラベルを変えることができます。フォルダーの meta.ts ファイルもロケールごとに解決されます: 既定の dir パーサーでは、fr/guides/ の下に meta.ts を置けばフランス語のグループを独立して並べ替えられます。dot パーサーでは翻訳が元のファイルの隣にあるため、フォルダーの meta.ts はすべてのロケールに適用されます。ナビゲーションに関するその他の挙動は、言語ごとに同様に動作します。

ヘッダータブはコンテンツから導出されるのではなく設定されるものなので、そのラベルは blume.config.ts でローカライズします: タブの label は、単純な文字列形式に加えてロケールごとのマップ({ en: "Docs", fr: "Documentation" })を受け付け、記入していないロケールについてはデフォルトロケールのエントリにフォールバックします。タブを参照してください。

フォールバック

ページがまだ翻訳されていない場合、Blume はローカライズされた URL でフォールバックロケールのコンテンツをレンダリングします — そのためリンクは機能し、ページは完全に事前レンダリングされ、検索エンジンが行き止まりに送られることもありません。フォールバックの既定値は defaultLocale です:

i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}

フォールバックページは検索インデックスから除外され、hreflang でも実際の翻訳としては通知されません。そのため未翻訳のコンテンツがランキングを奪い合うことはありません。それでもそのロケールのサイドバーには表示されるので、ナビゲーションは完全なまま保たれます — 読者はどの言語でもすべてのページに到達できます。

エージェントによる翻訳

ロケールを手作業で埋める必要はありません。blume translate は各ロケールで欠落している、または古くなっているページをすべて見つけ出し、ローカルのエージェント CLI(Claude Code または Codex)で翻訳します:

blume translate --claude

Blume は各結果の構造 — フロントマター、コードフェンス、リンク — を検証し、ファイルの書き込みも自身で行います。エージェントはテキストを翻訳するだけです。コミットされる台帳(blume.translations.json)が、各翻訳がどのソースリビジョンに由来するかを追跡するため、再実行時には変更があったものだけが対象となり、手作業で書いた翻訳はそのまま採用され、上書きされることはありません。CI では、ソースページが翻訳より先に進んでいる場合に blume translate --check が失敗します。

言語スイッチャー

i18n を有効にすると、locales から生成された言語スイッチャーがヘッダーに自動的に表示されます。各ページについて、あらゆる言語の対応する翻訳へリンクし、翻訳が存在しない場合はフォールバックページへリンクして未翻訳であることを示します。設定は一切不要です。

翻訳された UI

Blume は自身のインターフェース回りの文言 — 「このページの内容」「検索」「GitHub で編集」など — の翻訳を標準で同梱しているため、組み込みパックのあるロケールでは初めから翻訳済みの UI が使えます。翻訳するのはコンテンツだけです。

パックは 30 を超える言語に対応しています — アラビア語、ベンガル語、ブルガリア語、カタルーニャ語、中国語(簡体字・繁体字)、クロアチア語、チェコ語、デンマーク語、オランダ語、フィンランド語、フランス語、ドイツ語、ギリシャ語、ヘブライ語、ヒンディー語、ハンガリー語、インドネシア語、イタリア語、日本語、韓国語、ノルウェー語、ペルシャ語、ポーランド語、ポルトガル語(およびブラジルポルトガル語)、ルーマニア語、ロシア語、セルビア語、スロバキア語、スペイン語、スウェーデン語、タイ語、トルコ語、ウクライナ語、ベトナム語。これらはコミュニティによって保守されています — ロケールの追加や翻訳の改善は PR を送ってください。

欠落している文字列や未同梱の文字列は、デフォルトロケール、次に英語へフォールバックします。文字列を上書きしたり独自の言語を提供したりするには、ロケールをキーとして i18n.ui を設定します:

i18n: {
  // …
  ui: {
    fr: {
      search: { button: "Rechercher", placeholder: "Rechercher…" },
      page: { previous: "Précédent", next: "Suivant" },
    },
  },
}

SEO

ローカライズされた SEO は自動的に処理されます — ページごとにメタデータを書く必要はありません:

• <html lang> と dir はアクティブなロケールから設定されます。
• hreflang の代替リンクはページの実際の翻訳をすべてリンクし、加えてデフォルトロケールを指す x-default も出力します。
• 正規 URL はロケールに応じた正しいものになり、JSON-LD には inLanguage が含まれます。

これらを絶対 URL として出力できるように、deployment.site を設定してください。

検索

検索はアクティブな言語にスコープされます: /fr/… のページではダイアログがフランス語の結果を返し、すべての言語 トグルで一度にすべてのロケールを横断して検索できます。既定の(Orama)および FlexSearch のインデックスはブラウザー側でフィルタリングし、ホスト型プロバイダーは各レコードに locale ファセットを持たせます。

右から左

ロケールに dir: "rtl" を設定すると、Blume はインターフェース全体 — サイドバー、ヘッダー、目次、ページネーション、検索、メニュー — をミラーリングし、<html dir> もそれに合わせて設定します。意図的に左から右のままにしているものが 2 つあります: コードブロック(コードはどの言語でも LTR で読みます)と フォールバックコンテンツ — 未翻訳のページは実際に書かれている言語の方向を維持するため、RTL ロケールの下で表示される英語も正しく読める一方、周囲の UI はミラーリングされます。

次はどこへ