国际化 (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 运行。

不要给默认区域设置添加前缀

任何给默认区域设置添加前缀的 Astro 路由策略都会破坏 EmDash 管理界面——这包括 routing: { prefixDefaultLocale: true } 和 routing: "prefix-always"。启用其中任何一个后，所有页面路由——包括集成注入的路由——都需要区域设置前缀，因此 /_emdash/admin 及其所有子路径（/setup、/login、/content 等）都会返回 404。带区域设置前缀的变体（/es/_emdash/admin/...）也不起作用，因为管理界面的客户端路由器期望位于 /_emdash/admin。/_emdash/api/* 下的 API 路由不受影响——只有带展开参数的注入页面路由会出问题。这是 Astro 上游关于 i18n 路由与 injectRoute 交互方式的限制（参见 #369）。

改用 Astro 的默认路由策略（prefix-other-locales），它以不带前缀的方式提供默认区域设置，并且与管理界面兼容：

i18n: {
	defaultLocale: "en",
	locales: ["en", "fr", "es"],
	fallback: { fr: "en", es: "en" },
	// 没有 `routing` 块——默认值 (prefix-other-locales) 是兼容的
},

如果你需要为公共页面给默认区域设置添加前缀，请在站点前端使用重定向或重写（例如在边缘处 / → /en/）来处理，而不是使用 prefixDefaultLocale。

翻译的工作原理

EmDash 使用每区域设置一行的模型。每个翻译都是数据库中自己的行，拥有自己的 ID、slug 和状态，通过共享的 translation_group 标识符与其他翻译关联。一个包含三个翻译的文章表如下所示：

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 自然工作
每区域设置的发布 — 发布英语版本同时保持法语为草稿
每区域设置的修订 — 每个翻译有自己的修订历史
单区域设置查询 — 列表查询仅返回一个区域设置的条目

查询翻译内容

单个条目

将 locale 传递给 getEmDashEntry 以检索特定翻译。省略时，默认为请求的当前区域设置（由 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>

从管理界面的菜单列表中创建现有菜单的翻译——项目会保留 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 中的精确大小写。更新前，检查是否存在相同分类法名称和目标区域设置的行，或相同术语名称、slug 和目标区域设置的行。这些组合是唯一的；如果目标行已经存在，请调和翻译而不是应用批量区域设置更新。重启 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} 的默认 slug。根据需要调整 slug 和内容，然后保存。

按区域设置发布

每个翻译有自己的状态。独立发布、取消发布或计划翻译。法语版本可以是草稿而英语版本是上线状态。

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、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 命名空间的普通站点地图。

页面头部中的 hreflang 替代项

相同的替代项属于每个内容页面的 <head>。如果你的布局使用 <EmDashHead>，这是自动的：当 i18n 启用且页面上下文包含 content 时，它为每个已发布的翻译兄弟输出一个 <link rel="alternate">——包括 Google 推荐的自引用链接——加上 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 工作流相同，在导入完成后应用。

下一步

查询内容 — 完整查询 API 参考
内容操作 — 管理界面内容管理
Astro i18n 路由 — Astro 的路由配置