今天折腾了将近一上午的博客多语言配置，差点把我折腾死了。

我先是搜索hugo stack主题多语言配置，找到主题作者写的官方文档看。然而官方文档对这部分并没有详细介绍，并且example site 没有配置多语言。我转而去看hugo的官方文档，把配置文件改了，但是出现了一个十分抽象的问题：“语言切换按钮不显示文字”。

这个问题可把我折磨疯了，用开发者模式查看组件，发现是这个list里没有languageName值，然而我是在配置文件中写入了这些值的。我又去google相似问题，然而一无所获。我跟着尝试找到该主题的仓库，看它layout里的sidebar的实现，仍然无济于事。

正当我百无头绪的时候，我发现这个配置文件长得不太一样。

1
2
3

_language.toml
menu.toml
...

这个_language.toml的配置文件前面有个下划线，我突然反应过来，这个文件应该是被作为默认配置继承的，如果把下划线去掉，估计这个问题就解决了。

果然成功了，为了搞清楚，我又去询问了GPT，原来在hugo中以_开头的文件同寻常文件作用不同。

页面中以_开头的.md文件，适用于章节或目录，而不是单独的页面，是用来定义某个目录的元数据和内容。

例如，在blog目录中，_index.md决定了blog页面显示的内容，而post1.md和post2.md是blog路径下的列表页。

1
2
3
4
5

content/
│── blog/
│   ├── _index.md  # 定义 /blog/ 页面
│   ├── post1.md   # /blog/post1/
│   ├── post2.md   # /blog/post2/

不以_开头的.md文件，适用于单独的内容页面，即该目录只表示一个独立的页面，而非一个列表。

在下面这个例子中，/about就是一个独立的页面，而不是一个列表页。

1
2
3
4

content/
│── about/
│   ├── index.md   # 这个目录代表 /about/ 页面
│   ├── image.jpg  # 这个页面的资源

配置文件中也存在着区别。_开头的配置文件，是全局默认语言配置，作用于所有语言，提供默认的语言配置。在多语言站点中，它定义了所有语言的通用配置，适用于所有语言。站点的所有语言都会继承_language.toml中的配置，但可以在 language.toml中进行覆盖。

1
2
3
4

[language]
weight = 1
dateFormat = "2006-01-02"
defaultContentLanguage = "en"

这里定义了一个全局默认语言，所有语言都会继承 dateFormat 和 defaultContentLanguage。

而不以_开头的配置文件，作用于特定语言，用于覆盖_language.toml中的默认值。

1
2
3
4

[language]
weight = 2
dateFormat = "2006年01月02日"
languageCode = "zh-CN"

Hugo 解析 config/ 目录下的配置时，按照以下顺序应用：

• _language.toml（全局默认语言配置）
• language.toml（覆盖全局默认值）
• language.{languageCode}.toml（覆盖特定语言的值）

如果 language.toml 和 language.zh.toml 存在相同的键，language.zh.toml 的优先级更高。

找个时间针对这个问题写一篇博文，希望可以让使用这个主题的朋友避免和我一样踩坑。