E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

国際化 (i18n)

このページ

EmDash は Astro の組み込み i18n ルーティングと統合し、多言語コンテンツ管理を提供します。Astro が URL ルーティングとロケール検出を処理し、EmDash が翻訳コンテンツの保存と取得を処理します。

各翻訳は独自のスラッグ、ステータス、リビジョン履歴を持つ完全で独立したコンテンツエントリです。投稿のフランス語版が下書きのまま、英語版が公開されている状態が可能です。

設定

Astro 設定に i18n ブロックを追加して i18n を有効にします。EmDash はこの同じ設定からロケールリスト、デフォルトロケール、フォールバックチェーンを読み取ります。

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr", "es"],
		fallback: { fr: "en", es: "en" },
	},
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Astro 設定に i18n がない場合、すべての i18n 機能は無効になり、EmDash は単一言語の CMS として動作します。

翻訳の仕組み

EmDash は ロケールごとの行 モデルを使用します。各翻訳はデータベース内の独自の行で、独自の ID、スラッグ、ステータスを持ち、共有の translation_group 識別子を介して他の翻訳とリンクされています。3つの翻訳を持つ投稿テーブルは以下のようになります：

ec_posts:
id       | slug        | locale | translation_group | status
---------|-------------|--------|-------------------|----------
01ABC... | my-post     | en     | 01ABC...          | published
01DEF... | mon-article | fr     | 01ABC...          | draft
01GHI... | mi-entrada  | es     | 01ABC...          | published

この設計は以下を意味します：

  • ロケールごとのスラッグ — /blog/my-post と /fr/blog/mon-article が自然に機能
  • ロケールごとの公開 — フランス語を下書きのまま英語版を公開
  • ロケールごとのリビジョン — 各翻訳は独自のリビジョン履歴を持つ
  • 単一ロケールクエリ — リストクエリは1つのロケールのエントリのみを返す

翻訳されたコンテンツのクエリ

単一エントリ

getEmDashEntry に locale を渡して特定の翻訳を取得します。省略すると、リクエストの現在のロケール（Astro の i18n ミドルウェアで設定）がデフォルトになります。

---
import { getEmDashEntry } from "emdash";

const { slug } = Astro.params;
const { entry: post, error } = await getEmDashEntry("posts", slug, {
  locale: Astro.currentLocale,
});

if (!post) return Astro.redirect("/404");
---

<article>
  <h1>{post.data.title}</h1>
</article>

フォールバックチェーン

リクエストされたロケールにコンテンツが存在しない場合、EmDash は Astro 設定で定義されたフォールバックチェーンに従います。fallback: { fr: "en" } の場合：

  1. リクエストされたロケール（fr）を試す
  2. フォールバックロケール（en）を試す
  3. デフォルトロケールを試す

フォールバックは単一エントリクエリにのみ適用されます。リストクエリはリクエストされたロケールのエントリのみを返します。

メニュー

メニューはロケールごとです — 同じ name（例："primary"）が複数のロケールに存在でき、すべて共有の translation_group でリンクされています。メニュー項目はアクティブなロケールの参照コンテンツバージョンに対してコンテンツ参照を解決します。

以下のコンポーネントはアクティブなロケールのプライマリメニューを取得します：

---
import { getMenu } from "emdash";

const menu = await getMenu("primary", { locale: Astro.currentLocale });
---

<nav aria-label="Primary">
  <ul>
    {menu?.items.map((item) => (
      <li><a href={item.url}>{item.label}</a></li>
    ))}
  </ul>
</nav>

アドミンの メニュー リストから既存メニューの翻訳を作成します — 項目は reference_id がそのまま（参照コンテンツの translation_group を保存）でクローンされるので、新しいメニューのリンクは自動的に正しいロケールごとのコンテンツを指します。

タクソノミー（カテゴリ、タグ）

ターム はロケールごとです。定義（_emdash_taxonomy_defs）もロケールごとなので、label / labelSingular も翻訳できます。ピボット content_taxonomies.taxonomy_id はタームの translation_group を保存するので、単一の割り当てがコンテンツのすべてのロケールにまたがります。

以下の例はアクティブなロケールのカテゴリと投稿のタームを取得します：

---
import { getTaxonomyTerms, getEntryTerms } from "emdash";

const categories = await getTaxonomyTerms("category", {
  locale: Astro.currentLocale,
});
const terms = await getEntryTerms("posts", post.id, undefined, {
  locale: Astro.currentLocale,
});
---

コンテンツを翻訳すると、ソースのターム割り当てを自動的に継承します — ターム自体 を一度翻訳するだけでよく、それらを使用するすべての投稿が読み取り時に正しいロケールに解決します。

タクソノミーロケール不一致の修復

アドミンがサイトマニフェストを読み込む際、タクソノミー定義またはタームがサイトの設定された i18n.locales にないロケールを使用している場合、EmDash はサーバーログで警告します。i18n 設定がない場合、en が有効なロケールです。EmDash は既存コンテンツがどの設定されたロケールを使用すべきかを推論できないため、これらの行は変更されません。

データベースをバックアップし、警告で指定された影響を受ける行を調べます：

SELECT id, name, locale FROM _emdash_taxonomy_defs ORDER BY name, locale;
SELECT id, name, slug, locale FROM taxonomies ORDER BY name, slug, locale;

各行の意図されたロケールを確認した後、id で更新します：

UPDATE _emdash_taxonomy_defs SET locale = 'ja' WHERE id = '<definition-id>';
UPDATE taxonomies SET locale = 'ja' WHERE id = '<term-id>';

i18n.locales の正確な大文字小文字を使用してください。更新前に、同じタクソノミー名とターゲットロケール、または同じターム名、スラッグ、ターゲットロケールの行が存在するか確認してください。これらの組み合わせはユニークです。ターゲット行が既に存在する場合は、一括ロケール更新を適用する代わりに翻訳を調整してください。EmDash を再起動し、警告が表示されなくなったことを確認してください。

コレクション一覧

ロケールでコレクションをフィルタリング：

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
  locale: Astro.currentLocale,
  status: "published",
});
---

<ul>
  {posts.map((post) => (
    <li><a href={`/${post.data.slug}`}>{post.data.title}</a></li>
  ))}
</ul>

言語スイッチャー

getTranslations を使用して、現在のエントリの既存の翻訳にリンクする言語スイッチャーを構築します：

---
import { getTranslations } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

interface Props {
  collection: string;
  entryId: string;
}

const { collection, entryId } = Astro.props;
const { translations } = await getTranslations(collection, entryId);
---

<nav aria-label="言語">
  <ul>
    {translations.map((t) => (
      <li>
        <a
          href={getRelativeLocaleUrl(t.locale, `/blog/${t.slug}`)}
          aria-current={t.locale === Astro.currentLocale ? "page" : undefined}
        >
          {t.locale.toUpperCase()}
        </a>
      </li>
    ))}
  </ul>
</nav>

getTranslations 関数は同じ翻訳グループ内のすべてのロケールバリアントを返します：

const { translationGroup, translations } = await getTranslations("posts", post.entry.id);
// translations: [
//   { locale: "en", id: "01ABC...", slug: "my-post", status: "published" },
//   { locale: "fr", id: "01DEF...", slug: "mon-article", status: "draft" },
// ]

アドミンでの翻訳管理

コンテンツリスト

i18n が有効な場合、コンテンツリストには以下が表示されます：

  • 各エントリのロケールを表示する ロケール列
  • ロケール間を切り替えるツールバーの ロケールフィルター

翻訳の作成

エディターで任意のコンテンツエントリを開きます。サイドバーにすべての設定されたロケールをリストする 翻訳 パネルが表示されます。各ロケールについて：

  • 翻訳のないロケールには 「翻訳」 が表示されます — クリックして作成
  • 既存の翻訳があるロケールには 「編集」 が表示されます — クリックしてナビゲート
  • 現在のロケールにはチェックマークが付きます

翻訳を作成する際、新しいエントリはソースロケールのデータで事前入力され、デフォルトスラッグ {source-slug}-{locale} が割り当てられます。必要に応じてスラッグとコンテンツを調整し、保存します。

ロケールごとの公開

各翻訳は独自のステータスを持ちます。翻訳を独立して公開、非公開、またはスケジュールします。フランス語版が下書きのまま英語版がライブであることが可能です。

Content API

ロケールパラメーター

すべてのコンテンツ API ルートはオプションの locale クエリパラメーターを受け付けます：

GET /_emdash/api/content/posts?locale=fr
GET /_emdash/api/content/posts/my-post?locale=fr

省略すると、設定されたデフォルトロケールが使用されます。

API 経由で翻訳を作成

コンテンツ作成エンドポイントに locale と translationOf を渡して翻訳を作成します：

POST /_emdash/api/content/posts
Content-Type: application/json

{
  "locale": "fr",
  "translationOf": "01ABC...",
  "data": {
    "title": "Mon Article",
    "slug": "mon-article"
  }
}

新しいエントリはソースエントリの translation_group を共有し、下書きとして開始されます。

翻訳の一覧

指定されたエントリのすべての翻訳を取得：

GET /_emdash/api/content/posts/01ABC.../translations

翻訳グループ ID と、ID、スラッグ、ステータスを含むロケールバリアントの配列を返します。

CLI

CLI はコンテンツコマンドで --locale フラグをサポートします：

# フランス語の投稿を一覧
emdash content list posts --locale fr

# 特定のエントリをフランス語で取得
emdash content get posts my-post --locale fr

# 既存エントリのフランス語翻訳を作成
emdash content create posts --locale fr --translation-of 01ABC...

多言語コンテンツのシード

シードファイルは locale と translationOf を使用して翻訳を表現します：

{
  "content": {
    "posts": [
      {
        "id": "welcome",
        "slug": "welcome",
        "locale": "en",
        "status": "published",
        "data": { "title": "Welcome" }
      },
      {
        "id": "welcome-fr",
        "slug": "bienvenue",
        "locale": "fr",
        "translationOf": "welcome",
        "status": "draft",
        "data": { "title": "Bienvenue" }
      }
    ]
  }
}

ソースロケールエントリは、translationOf 参照が正しく解決されるように、シードファイル内でその翻訳の前に表示される必要があります。

フィールドの翻訳可能性

各フィールドには translatable 設定があります（デフォルト：true）。翻訳を作成する際：

  • 翻訳可能なフィールド は編集用にソースロケールから事前入力されます
  • 翻訳不可のフィールド はコピーされ、グループ内のすべての翻訳で同期が保たれます

status、published_at、author_id などのシステムフィールドは常にロケールごとで、同期されません。

URL 戦略

EmDash はロケール URL を管理しません — Astro がルーティングを処理します。一般的なパターン：

# prefix-other-locales（Astro デフォルト）
/blog/my-post          → en（デフォルトロケール、プレフィックスなし）
/fr/blog/mon-article   → fr

# prefix-always
/en/blog/my-post       → en
/fr/blog/mon-article   → fr

ルーティングモードに関係なく正しい URL を構築するには、astro:i18n の getRelativeLocaleUrl を使用します。

サイトマップ

/sitemap-{collection}.xml のコレクションごとのサイトマップはロケール対応です。i18n が有効な場合、各翻訳は独自の <url> エントリとして出力され、ロケールプレフィックスは Astro の getRelativeLocaleUrl で解決されます。prefixDefaultLocale 設定やカスタムロケール path マッピングは自動的に尊重されます。

翻訳の兄弟は xhtml:link 代替でクロスリンクされ、検索エンジンが各ユーザーに正しい言語を提供できます：

<url>
  <loc>https://example.com/blog/hello</loc>
  <lastmod>2026-05-28T16:33:15.461Z</lastmod>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/blog/hello" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/blog/bonjour" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/blog/hello" />
</url>

兄弟は translation_group でグループ化されるので、後で追加された行（既存投稿の新しいロケールバリアント）は他のすべてのバリアントで自動的に代替として表示されます。単一ロケールのサイトは xhtml 名前空間なしのプレーンなサイトマップを生成します。

ページヘッドの hreflang 代替

同じ代替はすべてのコンテンツページの <head> に属します。レイアウトが <EmDashHead> を使用している場合、これは自動です：i18n が有効でページコンテキストに content が含まれている場合、公開された翻訳兄弟ごとに <link rel="alternate"> を出力します — Google が推奨する自己参照リンクを含む — plus x-default：

<link rel="alternate" hreflang="en" href="https://example.com/blog/hello" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/blog/bonjour" />
<link rel="alternate" hreflang="x-default" href="https://example.com/blog/hello" />

手書きの head の場合、getHreflangAlternates で代替を解決します：

---
import { getEmDashEntry, getHreflangAlternates } from "emdash";

const { entry } = await getEmDashEntry("posts", Astro.params.slug);
const alternates = await getHreflangAlternates("posts", entry.data.id, {
	siteUrl: Astro.url.origin,
});
---

<head>
	{alternates.map((a) => <link rel="alternate" hreflang={a.hreflang} href={a.href} />)}
</head>

動作はサイトマップと完全に一致します：

  • x-default はデフォルトロケールバリアントを指します。デフォルトロケールに公開された翻訳がない場合、最初のルーティング可能なバリアントにフォールバックするので、セットに x-default が欠けることはありません。
  • 未公開の兄弟は除外されます — 下書きの翻訳は代替に漏れません。
  • ルーティング不可能なロケールは削除されます。 設定された i18n.locales にないロケールの行は提供できず、検索エンジンを 404 にリンクするのはリンクなしよりも悪いです。
  • 未翻訳のエントリ は i18n が有効な場合でも自己参照の代替と x-default を取得し、サイトマップを反映します。
  • i18n が無効 の場合、結果は空でクエリは実行されません。

URL はコレクションの urlPattern から構築され、Astro i18n ルーティング設定（prefixDefaultLocale、カスタムロケール path マッピング）を通じてローカライズされるので、head とサイトマップは常に一致します。

多言語コンテンツのインポート

アドミンの移行ツールを通じて WordPress コンテンツをインポートします — コンテンツインポート と WordPress からの移行 を参照。WXR エクスポートは WPML や Polylang が追加するロケールと翻訳グループの構造を持たないため、インポートされたコンテンツはデフォルトロケールに配置されます。

インポートされたコンテンツから翻訳を構築するには、翻訳されたエントリを作成してオリジナルにリンクします：

emdash content create posts --locale fr --translation-of 01ABC...

これは上記の 多言語コンテンツのシード で示した --locale / --translation-of と同じワークフローで、インポート完了後に適用されます。

次のステップ