国際化（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つの翻訳を持つpostsテーブルは次のようになります：

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>

管理画面のMenusリストから既存メニューの翻訳を作成します — 項目は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,
});
---

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

コレクション一覧

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

---
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="Language">
  <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が有効な場合、コンテンツリストには以下が表示されます：

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

翻訳の作成

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

• 翻訳のないロケールには**“Translate”**が表示 — クリックして作成
• 既存の翻訳があるロケールには**“Edit”**が表示 — クリックして移動
• 現在のロケールはチェックマークでマーク

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

ロケールごとの公開

各翻訳には独自のステータスがあります。翻訳を独立して公開、非公開、またはスケジュールします。フランス語版が下書きのままで英語版が公開されている場合があります。

コンテンツ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名前空間のないプレーンなサイトマップを生成します。

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

管理画面の移行ツールを介してWordPressコンテンツをインポート — Content ImportとMigrate from WordPressを参照。WXRエクスポートにはWPMLやPolylangが追加するロケールと翻訳グループ構造が含まれないため、インポートされたコンテンツはデフォルトロケールに配置されます。

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

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

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

次のステップ

• Querying Content — クエリAPI完全リファレンス
• Working with Content — 管理画面でのコンテンツ管理
• Astro i18n routing — Astroのルーティング設定