E EmDash CMS Everything Guides, use cases, plugins, templates
简体中文

国际化 (i18n)

本页内容

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

查询翻译内容

单个条目

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

  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,
});
---

翻译内容会自动继承源的术语分配 — 您只需要翻译术语本身一次，使用它们的每篇文章都会在读取时解析为正确的语言环境。

集合列表

按语言环境过滤集合：

---
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 后，内容列表显示：

  • 显示每个条目的语言环境的语言环境列
  • 工具栏中的语言环境过滤器，用于在语言环境之间切换

创建翻译

在编辑器中打开任何内容条目。侧边栏显示一个翻译面板，列出所有配置的语言环境。对于每个语言环境：

  • “翻译” — 对于没有翻译的语言环境显示 — 单击以创建一个
  • “编辑” — 对于具有现有翻译的语言环境显示 — 单击以导航到它
  • 当前语言环境用复选标记标记

创建翻译时，新条目会预先填充源语言环境的数据，并分配默认 slug {源-slug}-{语言环境}。根据需要调整 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，无论路由模式如何。

导入多语言内容

通过管理员迁移工具导入 WordPress 内容 — 请参阅内容导入和从 WordPress 迁移。WXR 导出不包含 WPML 或 Polylang 添加的语言环境和翻译组结构，因此导入的内容会到达您的默认语言环境。

要从导入的内容构建翻译，请创建翻译的条目并将其链接到原始条目：

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

这与上面多语言内容种子中显示的 --locale / --translation-of 工作流程相同，在导入完成后应用。

后续步骤