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

Blume は 1 つのプロジェクトを多言語で配信します。翻訳したファイルを適切な場所に置くだけで、Blume がルーティング、言語スイッチャー、ロケールごとのナビゲーション、SEO を自動的に設定します — 別途メンテナンスすべきルーティングレイヤーはありません。オプトイン方式なので、`i18n` ブロックがなければサイトはこれまでどおり単一言語のままです。[バージョニング](/docs/content/versioning)とも組み合わせられます — 凍結されたスナップショットは翻訳を保持し、ロケールのフォールバックは各バージョン内で機能します。

## 有効にする [#enable-it]

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

```ts blume.config.ts lineNumbers
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`](/docs/reference/translate) にそのロケール向けの自由記述のガイダンス — 文体、方言、用語法、たとえば `"Brazilian Portuguese, informal você"` — を与えます。これにより、その選択はエージェント任せになるのではなく、最初の翻訳の時点から固定されます。

## 翻訳コンテンツを整理する [#organize-translated-content]

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

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

| ファイル                        | ルート                  |
| ------------------------------- | ----------------------- |
| `docs/index.mdx`                | `/`                     |
| `docs/guides/quickstart.mdx`    | `/guides/quickstart`    |
| `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` |

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

### ファイル名のサフィックス [#filename-suffixes]

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

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

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

### 共有ファイル [#shared-files]

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

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

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

## デフォルトロケールの URL [#default-locale-urls]

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

```ts blume.config.ts lineNumbers
i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}
```

## ロケールごとのナビゲーション [#per-locale-navigation]

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

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

## フォールバック [#fallbacks]

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

```ts blume.config.ts lineNumbers
i18n: {
  // …
  fallbackLocale: "en", // default; set to null to 404 instead
}
```

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

:::tip
まずは最も重要なページ — ホームページ、クイックスタート、主要なガイド — から翻訳し、残りはフォールバックに任せましょう。リンクを壊すことなく、時間をかけて翻訳を埋めていけます。
:::

## ロケールをまたぐリンク [#links-across-locales]

内部リンクは、翻訳ページを含むどの言語でも、デフォルトロケールで書くときと同じように — `[Setup](/guides/setup)`、`<Card href="/guides/setup">` のように — 記述します。ページがロケールプレフィックスの下でレンダリングされるとき、Blume はルートからの相対パスで書かれた各ページリンクを、そのルートがそのロケールで — 実際の翻訳としてであれ、フォールバックページとしてであれ — 配信されている限り、そのロケール(`/fr/guides/setup`)へ移し替えます。ロケールごとのバリアントがないリンク — カスタムページ、生成されたルート、あるいはフォールバックを無効にしたサイトで翻訳が欠けている場合 — は、404 を指す代わりに記述されたままのリンク先を保ちます。また、すでにロケールプレフィックスを持つリンク(`/de/guides/setup`)はそのまま残されるため、ロケールをまたぐリンクは明示的なまま保たれます。

アンカーはリンクとともに移動するため、見出しの id は言語間で一致している必要があります。[`blume translate`](/docs/reference/translate) はこれを引き受けます: 翻訳された各見出しは、末尾の `[#id]` マーカーによってソースの見出しの id に固定されます。手作業で書く翻訳では、同じ [`[#custom-id]` マーカー](/docs/content/syntax#custom-anchors)を使って自分で見出しを固定してください — そうしないと `#ordering` はフランス語ページの自動生成された `#ordre` と一致せず、`blume validate` が、読者が実際にたどり着く翻訳ページに対する不一致として報告します。

## エージェントによる翻訳 [#translating-with-an-agent]

ロケールを手作業で埋める必要はありません。[`blume translate`](/docs/reference/translate) は各ロケールで欠落している、または古くなっているページをすべて見つけ出し、ローカルのエージェント CLI([Claude Code](https://claude.com/claude-code) または [Codex](https://developers.openai.com/codex/cli))で翻訳します:

```bash
blume translate --claude
```

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

## 言語スイッチャー [#the-language-switcher]

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

## 翻訳された UI [#translated-ui]

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

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

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

```ts blume.config.ts lineNumbers
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`](/docs/deployment) を設定してください。

## 検索 [#search]

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

## 右から左 [#right-to-left]

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

## 次はどこへ [#where-to-next]

**[ナビゲーション](/docs/content/navigation)**

各ロケールのサイドバー、並び順、タブを設計します。

**[発見しやすさ](/docs/discoverability)**

サイトマップ、Open Graph、構造化データ。