作者：Kuqilin（kuqilin@outlook.com）

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 站点。祝写作愉快！

本文2026-08-01首發於Kuqilin's Blog，最後修改於2026-08-01

本博客所有文章除特别聲明外，均采用 BY-NC-SA 許可協議。轉載請註明出處！

作者：Kuqilin（kuqilin@outlook.com）

Tip

请务必先通读全文再进行操作，避免一些不必要的错误。

安装 Hugo

Windows

前往官网下载 Hugo 的exe文件，随便找个位置放，然后把他添加到环境变量中即可。

Linux

先安装 Hugo 的二进制文件，可以在官网上下载，也可以直接使用软件包管理器，考虑到apt更新极为缓慢，建议 Debian 系去官网下载deb包进行安装。

sudo apt install hugo    # Debian 系
yay -S hugo              # Arch 系

安装完成后，执行hugo version会看到类似如下的提示：

❯ hugo version  
hugo v0.164.0-ce2470e7012b5ab5fc4e10ebe4027e9f8d9e00dc+extended linux/amd64 BuildDate=2026-07-06T16:39:30Z VendorInfo=gohugoio

即安装完成。

创建项目

我们使用hugo new site <项目名称>来创建项目，比如：

❯ hugo new site myBlog  
Congratulations! Your new Hugo site was created in /home/kuqilin/myBlog.  
  
Just a few more steps...  
  
1. Change the current directory to /home/kuqilin/myBlog.  
2. Create or install a theme:  
  - Create a new theme with the command "hugo new theme <THEMENAME>"  
  - Install a theme from https://themes.gohugo.io/  
3. Edit hugo.toml, setting the "theme" property to the theme name.  
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".  
5. Start the embedded web server with the command "hugo server --buildDrafts".  
  
See documentation at https://gohugo.io/.

可以看到成功的提示，接下来cd到项目文件夹myBlog，按照提示进行配置。

创建或安装主题

显然，我们是可以自己创建主题的，但是为了白嫖方便，直接前往 Hugo Themes 下载一个称心的即可，这里选择了 hugo-theme-reimu 这个主题。

主题安装有几种方式，推荐使用 Git Submodule：

cd myBlog
git init
git submodule add https://github.com/D-Sketon/hugo-theme-reimu.git themes/hugo-theme-reimu

也可以直接下载主题压缩包，解压到themes文件夹下。

然后在 hugo.toml 中指定主题：

theme = "hugo-theme-reimu"

配置 hugo-theme-reimu

主题的配置文件默认在 themes/hugo-theme-reimu/config/_default/ 下。我们不应该直接修改主题文件，因为更新主题时会将其覆盖掉，所以应该在项目根目录的 config/_default/ 下创建同名文件来覆盖。我们把params.yml（主题参数）复制即可。

基础站点配置（hugo.toml）

baseURL = 'https://<你的用户名>.github.io/'
theme = "hugo-theme-reimu"
title = "xxx's Blog"       # 站点标题
locale = "zh-CN"           # 语言
languageName = "简体中文"   # 语言名称
hasCJKLanguage = true      # 是否包含 CJK 字符

[markup.highlight]         # 语法高亮（含代码块必须）
guessSyntax = true
noClasses = false

[markup.goldmark.renderer]
unsafe = true

[markup.goldmark.extensions.passthrough] # 含数学公式必须
enable = true
delimiters.block = [["\\[", "\\]"], ["$$", "$$"]]
delimiters.inline = [["\\(", "\\)"], ["$", "$"]]

unsafe = true 允许在 Markdown 中直接使用 HTML，passthrough 用于支持数学公式的 $...$ 和 $$...$$ 语法。

主题参数配置（params.yml）

在 config/_default/params.yml 中配置主题的各项功能，这里介绍几个关键项：

导航菜单：

menu:
  - name: home
    url: ""
  - name: archives
    url: "archives"
  - name: about
    url: "about"
  - name: friend
    url: "friend"

个人信息和头像：

author: <你的名字>
email: <你的邮箱>
avatar: "avatar.jpg"           # 放在 static/avatar/ 下
banner: "images/banner.webp"   # 放在 static/images/ 下

社交链接：

social:
  email: mailto:<你的邮箱>
  github: https://github.com/<你的用户名>
  twitter: https://twitter.com/<你的用户名>

侧边栏和小组件：

sidebar:
  position: left  # 左右可选
widgets:
  - category
  - tag
  - tagcloud
  - recent_posts

评论区（以 Waline 为例）：

comment:
  default: waline
waline:
  enable: true
  serverURL: "<你的 Waline 服务地址>"

启用功能：

toc: true                # 目录
dark_mode:
  enable: auto           # 自动跟随系统
math:
  mathjax:
    enable: true         # 数学公式
show_update_time: true   # 显示更新时间

更多配置项（鼠标特效、Live2D、字体、加载动画等）请参考主题官方文档。

配置完成后，运行 hugo server -D 即可在本地预览 http://localhost:1313。

其他内容

其他内容，比如更改鼠标指针、修改字体、文章头图、文章封面、网站主题色、短代码、友链等等，请查看官方文档，这里不再赘述。嘻嘻

部署到 GitHub Pages

部署的核心思路是把 Hugo 构建生成的 public/ 目录推送到 <用户名>.github.io 仓库。GitHub Pages 会自动将这个仓库的内容作为静态网站发布。

也就是说，我们需要两个仓库：

• 源码仓库（如 hugo-build）：放 Hugo 项目源文件（Markdown、配置、主题等）
• 页面仓库（<用户名>.github.io）：只放 public/ 里的静态文件

下面分别介绍手动推送和 GitHub Actions 自动推送两种方式。

方式一：手动推送到 github.io

最直接的方式——在本地执行 hugo 构建，然后把 public/ 目录的内容推到页面仓库。

1. 克隆页面仓库

git clone https://github.com/<你的用户名>/<你的用户名>.github.io.git public

如果 public/ 目录已存在（Hugo 构建会生成），先删掉再克隆。

2. 构建并推送

# 回到源码仓库根目录，先构建
hugo

# 进入 public 目录（此时它已经是页面仓库的克隆）
cd public

# 提交并推送
git add .
git commit -m "update"
git push origin main

每次更新博客时，重复上面几步即可。

3. 写个脚本简化操作

可以把以上步骤写成一个脚本 deploy.sh：

#!/bin/bash
echo "Building..."
hugo

echo "Deploying..."
cd public
git add .
git commit -m "update $(date '+%Y-%m-%d %H:%M:%S')"
git push origin main
cd ..
echo "Done!"

以后只需运行 bash deploy.sh 就完成构建和部署了。

这种方式的优点是不依赖任何第三方 CI 服务，简单直接；缺点是需要手动执行，并且要保证本地 Hugo 环境正常。

方式二：GitHub Actions 自动部署

懒人必备——每次把源码推到 GitHub，剩下的构建和部署全交给 Actions 自动完成。

1. 创建 Personal Access Token

为了让 Actions 能够向页面仓库推送代码，需要一个 Token：

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens(classic)
2. 生成新 Token，勾选 repo 和 workflow 权限
3. 复制生成的 Token（注意：此 Token 只显示一次，务必保存好）

然后在源码仓库的 Settings → Secrets and variables → Actions 中新建一个 Secret，名称为 TOKEN，填入刚才复制的 Token。

2. 编写 Workflow 文件

在源码仓库根目录创建 .github/workflows/hugo.yaml：

name: deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
        - name: Checkout
          uses: actions/checkout@v4
          with:
              fetch-depth: 0
              submodules: true       # 如果主题用 git submodule 安装，需要这行

        - name: Setup Hugo
          uses: peaceiris/actions-hugo@v3
          with:
              hugo-version: "latest"
              extended: true

        - name: Build Web
          run: hugo

        - name: Deploy Web
          uses: peaceiris/actions-gh-pages@v4
          with:
              PERSONAL_TOKEN: ${{ secrets.TOKEN }}
              EXTERNAL_REPOSITORY: <你的用户名>/<你的用户名>.github.io
              PUBLISH_BRANCH: main
              PUBLISH_DIR: ./public
              commit_message: auto deploy

各步骤说明：

3. 推送源码触发部署

git add .
git commit -m "new post"
git push origin main

每次 push 到 main 分支后，GitHub Actions 就会自动运行。可以在源码仓库的 Actions 标签页查看构建进度，绿色 ✅ 即为部署成功，随后访问 https://<你的用户名>.github.io/ 就能看到更新后的博客。

两种方式对比

两种方式不冲突，可以同时使用——配好 Actions 后日常自动部署，偶尔需要手动推也完全可以。

至此，Hugo 博客的搭建、配置和部署就全部完成了 🎉

本文2026-07-11首發於Kuqilin's Blog，最後修改於2026-07-17

本博客所有文章除特别聲明外，均采用 BY-NC-SA 許可協議。轉載請註明出處！