國際化 (i18n) | EmDash CMS Everything

EmDash 與 Astro 內建 i18n 路由整合，提供多語言內容管理。Astro 處理 URL 路由和語言區域偵測；EmDash 處理翻譯內容的儲存與擷取。

每個翻譯都是完整、獨立的內容項目，擁有自己的 slug、狀態和修訂歷史。某篇文章的法語版可以是草稿，而英語版已發布。

設定

在 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、slug 和狀態，透過共用的 translation_group 識別碼與其他翻譯關聯。包含三種翻譯的 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

這種設計意味著：

按語言區域的 slug — /blog/my-post 和 /fr/blog/mon-article 自然可用
按語言區域發布 — 發布英語版同時保持法語版為草稿
按語言區域修訂 — 每個翻譯擁有獨立的修訂歷史
單語言區域查詢 — 清單查詢僅回傳一種語言區域的項目

查詢翻譯內容

單個項目

向 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" }：

嘗試請求的語言區域（fr）
嘗試回退語言區域（en）
嘗試預設語言區域

回退僅適用於單項目查詢。清單查詢僅回傳請求語言區域的項目。

選單

選單按語言區域劃分 — 相同的 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” — 點擊導覽
目前語言區域以勾選標記

建立翻譯時，新項目會預填來源語言區域的資料，並分配預設 slug {source-slug}-{locale}。根據需要調整 slug 和內容，然後儲存。

按語言區域發布

每個翻譯擁有獨立狀態。獨立發布、取消發布或排程翻譯。法語版可以是草稿，而英語版已上線。

內容 API

locale 參數

所有內容 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、slug 和狀態的語言區域變體陣列。

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

使用 astro:i18n 的 getRelativeLocaleUrl 建立正確的 URL，無論路由模式如何。

/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 內容 — 參見內容匯入和從 WordPress 遷移。WXR 匯出不包含 WPML 或 Polylang 新增的語言區域和翻譯組結構，因此匯入的內容會進入您的預設語言區域。

要從匯入的內容建立翻譯，建立翻譯項目並將其連結到原始項目：

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

這與上文播種多語言內容中展示的相同 --locale / --translation-of 工作流程相同，在匯入完成後套用。

下一步

查詢內容 — 完整查詢 API 參考
使用內容 — 管理後台內容管理
Astro i18n 路由 — Astro 路由設定