Reimu 主题下的 i18n

Tips

建议先通读本文了解基本流程和坑以后在一步一步跟着操作。
因为作者表达能力欠佳，本文由作者写完之后交由 AI 进行润色。

虽然花时间翻译自己的文章并不常见，但既然做了，就记录一下完整流程，方便后来者。

为什么需要手动配置？

Hugo 本身支持多语言（i18n），但主题通常需要你按约定组织文件和配置。Reimu 主题默认只提供单语言结构，要启用多语言，你需要做三件事：

1. 重构内容文件夹，按语言分目录
2. 为每篇文章关联翻译（通过 translationKey）
3. 在配置文件中声明语言，并（如果使用非内置语言）补充主题的本地化文案和翻译文件

下面按步骤展开。

第一步：调整内容文件夹结构

Reimu 主题默认将文章放在 content/ 下（如 content/post/、content/about.md 等）。
多语言时，需在 content/ 下为每种语言单独建一个子文件夹，子文件夹名即为语言代码（如 zh-CN、en、yue）。

操作示例
假设你原有简体中文内容（zh-CN），现在要增加英文（en）和粤语（yue）：

1. 在 content/ 下新建 zh-CN/、en/、yue/ 文件夹。
2. 将原来 content/ 下的所有内容（about.md、post/ 等）整个移动或复制到 zh-CN/ 内（作为默认语言）。
3. 再将 zh-CN/ 下的内容复制到 en/ 和 yue/ 中，之后分别翻译各文件夹内的 .md 文件。

最终结构类似：

content/
├── en/
│   ├── about.md
│   ├── archives/
│   ├── friend.md
│   └── post/
├── yue/
│   ├── about.md
│   ├── archives/
│   ├── friend.md
│   └── post/
├── zh-CN/
│   ├── about.md
│   ├── archives/
│   ├── friend.md
│   └── post/
└── zh-TW/          # 可选，以此类推
    ├── about.md
    ├── archives/
    ├── friend.md
    └── post/

注意：原 content/ 根目录下不要再放置任何内容，否则 Hugo 会将其视为无语言归属的内容，可能引发混乱。

第二步：关联不同语言版本（translationKey）

Hugo 需要通过 translationKey 来识别哪些文件互为翻译。
在每个语言的对应文件中，frontmatter 里写上相同的 translationKey 值。

例如，在 content/zh-CN/about.md、content/en/about.md 和 content/yue/about.md 中都加入：

translationKey: about

同样，每篇博文（如 post/hello.md）也要在所有语言版本中设置相同的 translationKey（可以设置为文章标题的 slug 或自定义标识）。

为什么重要：没有这个字段，语言切换按钮将无法在文章页显示可切换的语言列表。

第三步：在 hugo.toml 中声明语言

完成文件夹结构后，构建时 Hugo 会找不到语言定义而喜提报错。你需要在 hugo.toml（或 config.toml）中为每一种语言添加配置。

基础配置示例（以粤语 yue 为例）：

[languages.yue]
  locale = "yue"                # 语言代码，需与文件夹名一致
  label = "粵語"                # 界面显示的语言名称（可自定义）
  hasCJKLanguage = true         # 若语言包含中日韩文字，设为 true
  contentDir = "content/yue"    # 指向该语言的内容文件夹
  weight = 2                    # 在语言切换列表中的排序，数值越小越靠前

其他语言（如英文）同理：

[languages.en]
  locale = "en"
  label = "English"
  hasCJKLanguage = false
  contentDir = "content/en"
  weight = 3

设置默认语言（避免浏览器语言偏好干扰）：

defaultContentLanguage = "zh-CN"   # 设为你的主语言

提示：weight 影响切换菜单中的顺序，建议为常用语言设较小值。

第四步：处理「主题未内置」的自定义语言

Reimu 主题自带了一些 UI 文案（如“复制成功”），但只在部分语言（如 en、zh-CN、ja 等）中预置了翻译。
如果你添加的语言不在主题支持列表中（例如泰文 th、粤语 yue 虽然主题可能未包含），则必须额外补充两处配置，否则构建时主题会因找不到对应语言的文案而报错。

4.1 补充 params.yml 中的文案翻译

主题的 UI 文案定义在 themes/reimu/config/_default/params.yml 中。
你需要将这份文件复制到项目根目录的 config/_default/params.yml（若没有则新建对应文件夹），然后在该文件中为你的语言添加所有字段。

例如，原文件中有 clipboard.success 字段：

clipboard:
  success: 
    en: Copy successfully (*^▽^*)
    zh-CN: 复制成功 (*^▽^*)
    yue: 複製成功 (*^▽^*)          # 新增 yue 的翻译
    zh-TW: 複製成功 (*^▽^*)
    ja: コピー成功 (*^▽^*)
    pt-BR: Copiado com sucesso (*^▽^*)

你需要检查所有带 i18n 的字段（如 comment.title、preloader.text 等），逐一为你的语言添加对应值。
注意：语言键（如 yue）必须与你在 hugo.toml 中 [languages.yue] 的 locale 值完全一致。

4.2 创建独立的 i18n 翻译文件

Hugo 本身需要一些基础翻译字符串（如月份名称、日期格式等），这些在主题的 i18n/ 文件夹中提供。
同样，将 themes/reimu/i18n/ 下的某个现有文件（如 zh-CN.yml）复制到项目根目录的 i18n/ 文件夹中，重命名为你的语言代码（如 yue.yml），然后将里面的字符串逐一翻译成你的语言。

如果不做这一步，Hugo 构建时会因为缺少翻译数据而报错（类似 missing translations）。

常见问题

• 切换语言后页面 404？
  检查 contentDir 路径是否正确，且每个语言文件夹内确有对应文件。

• 语言切换按钮不出现？
  确认所有互为翻译的文件都设置了相同的 translationKey，且至少有两个语言版本存在。

• 修改后仍报错？
  运行 hugo --cleanDestinationDir 清除缓存后重新构建，有时旧配置会残留。

• 只改 params.yml 还不够？
  确保同时完成了 4.1 和 4.2 两步，缺一不可。

总结

Reimu 主题的 i18n 配置虽不复杂，但步骤环环相扣。简记要点：

• 按语言分目录 → 加 translationKey → 声明语言配置
• 若使用非内置语言，额外补充主题 UI 文案（params.yml）和基础翻译（i18n/*.yml）

按照上述步骤操作，你就能拥有一个完美切换的多语言 Hugo 站点。祝写作愉快！