跳到主要内容

国际化工作流

这篇文档约束这个仓库以后新增文档或博客时同步完成英文翻译的标准方式。

站点使用 Docusaurus 内置 i18n：zh-Hans 是默认语言，英文通过 i18n/en/ 目录实现。根目录的 I18N.md 是完整的参考手册，这篇文档只关心"每次新增内容时该怎么做"。

核心原则​

1. 中文放 docs/ 和 blog/，英文放 i18n/en/ 镜像路径​

中文是默认语言，直接放在项目根目录的 docs/ 和 blog/ 下。英文翻译放在 i18n/en/ 下的对应插件目录，路径必须 1:1 镜像。

文档镜像规则：

docs/Linux/new-article.md
  → i18n/en/docusaurus-plugin-content-docs/current/Linux/new-article.md

docs/DataStructer/sorting-algorithms/sorting-basics.md
  → i18n/en/docusaurus-plugin-content-docs/current/DataStructer/sorting-algorithms/sorting-basics.md

博客镜像规则：

blog/2026-05-01-new-post.md
  → i18n/en/docusaurus-plugin-content-blog/2026-05-01-new-post.md

文件名必须完全一致，包括大小写和扩展名。

2. 只翻译人读的文字，不翻译代码和技术标识​

翻译范围：

内容是否翻译
title、description翻译
sidebar_position、tags、authors、slug保持一致
正文段落、标题翻译
代码块（```）不翻译
内联代码（`）不翻译
图片链接、JSX 组件、import / export不翻译
LaTeX 公式不翻译

3. 新目录必须同步创建 _category_.json​

如果新增了一个目录（不管是文档目录还是专题目录），英文镜像路径下必须有对应的 _category_.json，position 保持一致，label 和 description 翻译。

// docs/NewDir/_category_.json
{
  "label": "新目录",
  "position": 12,
  "link": {
    "type": "generated-index",
    "description": "中文描述。"
  }
}

// i18n/en/.../NewDir/_category_.json
{
  "label": "New Directory",
  "position": 12,
  "link": {
    "type": "generated-index",
    "description": "English description."
  }
}

4. 新标签必须同步更新 tags.yml​

如果文章使用了新标签，英文的 tags.yml 也要更新。permalink 保持一致，label 翻译。

# i18n/en/docusaurus-plugin-content-docs/current/tags.yml
New Tag:
  label: New Tag
  permalink: new-tag

标准流程：新增文档​

第一步：创建中文文档​

在 docs/ 下正常创建中文 .md 或 .mdx 文件。

第二步：创建英文翻译​

在 i18n/en/docusaurus-plugin-content-docs/current/ 下创建同名同路径文件，翻译 frontmatter 和正文。

frontmatter 对照：

# 中文
---
title: 自定义镜像与 Dockerfile 实践
sidebar_position: 6
description: 把临时调试、Dockerfile 构建整理成一套更稳妥的工作流。
---

# 英文
---
title: Custom Images and Dockerfile Practices
sidebar_position: 6
description: "Turning ad-hoc debugging and Dockerfile builds into a more reliable workflow."
---

注意：description 包含冒号时必须用引号包裹，否则 YAML 解析会报错。

第三步：如果是新目录，同步创建英文 _category_.json​

参照上面"核心原则"第 3 条。

第四步：如果使用了新标签，同步更新英文 tags.yml​

参照上面"核心原则"第 4 条。

第五步：如果新标签名是中文，刷新 sidebar 翻译​

npm run write-translations:en

然后编辑 i18n/en/docusaurus-plugin-content-docs/current.json，找到新增的 sidebar 条目翻译。

标准流程：新增博客​

与文档类似，但路径不同：

blog/2026-05-01-new-post.md
  → i18n/en/docusaurus-plugin-content-blog/2026-05-01-new-post.md

博客的 authors.yml 和 tags.yml 不需要翻译（已是英文或通用标识符）。

MDX 博客中的 export const 数据对象需要翻译其中的文字值（alt、caption 等），但图片 URL 不变。

MDX 兼容性陷阱​

英文翻译中最容易引入构建错误的几个地方：

1. 散文中的 <​

MDX 把 < 当 JSX 标签开始。数学比较必须转义：

❌ Small data (<1M elements)
✅ Small data (≤1M elements)
✅ Small data (&lt;1M elements)

2. 散文中的 {​

MDX 把 { 当 JSX 表达式。集合符号必须用 LaTeX 包裹：

❌ The set {a, b, c} has 3 elements.
✅ The set $\{a, b, c\}$ has 3 elements.

3. YAML frontmatter 中的冒号​

description 包含冒号时必须用引号包裹：

❌ description: Three patterns: temporary, persistent, and troubleshooting.
✅ description: "Three patterns: temporary, persistent, and troubleshooting."

4. LaTeX 中的花括号​

LaTeX 的 \{...\} 在 MDX 中仍会被解析为 JSX。确保在 $...$ 或 $$...$$ 分隔符内：

❌ $[a]_R = \{x \in A \mid (a,x) \in R\}$   ← 单行 $ 可能失效
✅ $$[a]_R = \{x \in A \mid (a,x) \in R\}$$  ← 用 $$ 更安全

5. 代码块内的中文注释​

代码块里的注释也应翻译：

// ❌ int visited[MAX]; // 访问标记数组
// ✅ int visited[MAX]; // Visited marker array

自定义页面的国际化​

Docusaurus 不会自动翻译自定义 React 页面和 theme override。这些页面需要通过 useDocusaurusContext().i18n.currentLocale 读取当前语言，在组件内维护对应文案。

当前受影响的页面：

  • 文档首页（src/components/DocsIntro/）
  • Travel 首页
  • Blog 总览页
  • 站点首页

如果修改或新增了这些页面的可见文案，必须同步处理中英文。

构建验证​

每次新增翻译后必须验证：

npm run build       # 构建全部 locale（zh-Hans + en）
npm run build:en    # 只构建英文，适合快速验证

构建必须零错误。常见错误来源：

  • YAML frontmatter 中未转义的冒号
  • MDX 中未转义的 < 和 {
  • 英文镜像路径下缺少 _category_.json
  • 文件名大小写不一致（Windows 不区分大小写，但 CI 环境会区分）

发布前检查清单​

每次新增内容并同步翻译后，至少检查：

  • 中文文件放在 docs/ 或 blog/ 下
  • 英文文件放在 i18n/en/ 对应镜像路径下
  • 文件名完全一致（包括扩展名）
  • sidebar_position 中英文一致
  • title 和 description 已翻译
  • tags、authors、slug 保持一致
  • 代码块内容未被翻译
  • 新目录有对应的英文 _category_.json
  • 新标签有对应的英文 tags.yml 条目
  • YAML description 中的冒号已用引号包裹
  • 散文中的 < 和 { 已转义或用 LaTeX 包裹
  • npm run build 通过