多语言站点最耗神的环节，往往不是写内容，而是盯住“哪一份还没写”。Zola 多语言站点里的未翻译内容，说到底是两件事叠在一起的结果：一是文件名约定决定了内容归属哪种语言，二是语言分组决定了同一篇内容的不同语言版本能不能被认成“一家人”。这两步里任何一步没对齐，构建照样成功，页面照样生成，可法语站或日语站的访客点进导航，看到的要么是 404，要么是英文原文，要么是空列表。这篇就从最表面的命名约定一路挖到分组逻辑的实现层面，把未翻译内容在哪些环节冒头、用什么姿势兜住，讲清楚。
适合两类人看：已经在 Zola 上跑着双语或多语站、正在被“某些页面只译了一半”折磨的维护者；以及正准备给站点加第二语言、想一开始就把目录约定设计对的人。哪怕你没读过 Zola 的源码，只要跟着走一遍文件名到分组键的推导过程，后面那些诡异现象基本都能自己对上号。
1. 未翻译内容的三种形态：先分清再动手
1.1 条目缺失、导航残留、聚合污染
很多人说“我的站点有未翻译内容”，实际上说的是三件不同的事，处理手段完全不一样，混在一起谈只会越改越乱。
第一种是条目缺失型：源语言有blog/rust-notes.zh.md，目标语言目录里压根没有rust-notes.en.md。这类最直观，但也最容易漏，因为构建不会报错，只在目标语言的列表页里少一条。判断方法很简单，把两种语言的content目录做一次文件名差集，缺哪些一目了然。
第二种是导航残留型：文章本身翻好了，但导航栏、页脚、侧边栏里还挂着指向未翻译页面的链接。这类问题的隐蔽之处在于，它不在内容层，而在模板层。模板里写死了一条/blog/，或者遍历section.pages时没做语言过滤，链接就指向了另一个语言版本的地址，点进去要么跳回默认语言站，要么直接 404。
第三种是聚合污染型：列表页、标签页、RSS、搜索索引这些“聚合产物”把不属于当前语言的内容也卷了进来。典型表现是英文站的标签云里混进了中文文章的标签，或者搜索框里搜出一堆你看不懂的文字。根源通常在于get_taxonomy或get_section调用时没传lang参数，拿到了默认语言的聚合结果。
我在实际项目里遇到的比例大概是：条目缺失占六成，导航残留占三成，聚合污染占一成。但造成线上事故的，八成是后两种——因为它们不影响构建，只在真实访问时暴露。
1.2 为什么 Zola 不做自动回退
这是新手最常问的问题：某篇文章没有英文版，为什么英文站不自动显示中文原文？
答案在 Zola 的设计取向里。Zola 把每种语言当成一套相对独立的站点来看待，而不是同一套内容的多视图。启动时它按default_language和各语言配置分别初始化和渲染，每种语言有自己的 section 树、自己的 taxonomy、自己的 sitemap 和 feed。这套设计的好处是干净：语言之间不会互相污染，一个语言站点出问题不会牵连其他语言；代价就是没有隐式的跨语言兜底。
get_page(path="blog/rust-notes", lang="en")如果那篇英文版不存在，返回的是构建错误，不是中文版。想要降级显示，必须自己在模板里先判断、再决定渲染什么。这个判断的依据，就是后面要讲的translations变量。
提示：不要试图用
default_language来“兜底”页面内容。它只决定根路径下内容的归属和部分默认行为，不会在目标语言缺失时自动搬运内容。
明白了这一点，后面的所有设计都是在解决同一个问题：如何在缺少某语言版本时，让构建结果依然体面。
2. 文件名约定：语言后缀是怎么被认出来的
2.1 后缀识别的优先级与边界
Zola 判断一份内容属于哪个语言，靠的是文件名里最后一个点分段。流程大致是：取文件的 stem（去掉.md），按.切开，拿最后一段去和config.toml里声明的语言代码比对；命中就是该语言，并且这个后缀会从路径里被剥掉；没命中，整段就当普通文件名的一部分。
举个例子，配置里声明了zh和en：
| 文件名 | 识别出的语言 | 最终 path |
|---|---|---|
about.md | 默认语言 | about |
about.zh.md | zh | about |
about.en.md | en | about |
about.fr.md | 默认语言 | about.fr |
my.notes.en.md | en | my.notes |
第四行是重灾区。fr没在配置里声明，于是它不但没被当成语言，还被塞进了 path，生成出来的地址是/about.fr/。这种错误不会报任何警告，只会在某天你加语言的时候突然发现整个目录结构全错位了。
第五行说明另一件事：只有最后一段参与语言判定。my.notes.en.md的多段文件名不会被误判，notes那段是安全的。所以文件名里带点是可以的，只要最后一段不是语言代码。
关于子目录里的_index.md，规则一样。content/blog/_index.zh.md会被识别为zh语言的blogsection；漏了后缀的content/blog/_index.md就是默认语言的blogsection。这一点很关键，因为 section 的语言和后缀如果不匹配，下面挂着的页面分组就会出问题。
2.2 path 才是分组主键，语言只是附属标签
这是整篇文章最核心的一句话：Zola 分组的依据是 path，不是文件名，也不是标题，更不是某种 ID。
about.zh.md和about.en.md剥掉语言后缀之后，path 都是about。Zola 在内部用这个 path 作为键，把两份内容归到同一组，互为翻译。about.zh.md和about-en.md（用连字符）就完全不是一回事，前者的 path 是about，后者的 path 是about-en，它们会被当成两篇独立的文章，永远互不认识。
这条规则带来的直接推论是：翻译版本必须放在同一个相对目录下，且文件名去掉语言后缀后完全一致。你不能把中文版放content/zh/blog/a.md、英文版放content/en/blog/a.md，那是另一套目录分语言的方案，Zola 原生的文件名约定不是这么工作的。硬要这么放也不是不行，但你会失去内建的translations关系，语言切换器得自己手搓映射表。
比较新的版本里，分组完全依赖 path；更早的版本曾允许在 front matter 里手动指定一个对齐用的字段。升级老站点时，如果发现某些页面的翻译关系突然断了，第一件事就是检查文件名约定是否满足“去后缀后 path 全等”。
2.3 三种常见命名错误与后果
错误一：大小写不一致。About.zh.md和about.en.md，去掉后缀后一个是大写开头一个是小写，path 不相等，分组失败。在大小写不敏感的文件系统上你看不出问题，部署到大小写敏感的构建环境才炸。
错误二：多打了连字符。about-zh.md、about-zh-CN.md这类写法，语言代码段不是独立的一个点分段，识别不出来，整个-zh进了 path。
错误三：section 和 page 的语言不匹配。content/blog/_index.md（默认语言）下面挂了content/blog/post.en.md。英文文章归属于默认语言的 section，英文站的get_section("blog", lang="en")拿不到这个 section，整个博客列表在英文站下就是空的。这种问题排查起来最费劲，因为单篇文章的 URL 是好的，只有列表页空。
注意：section 的语言归属决定了它下面所有页面的“可见性入口”。要让某语言的文章出现在该语言的列表页里，对应层级的
_index必须也有该语言版本。
3. 语言分组源码解析：一次 HashMap 归并
3.1 Library 的嵌套字典结构与插入顺序
抛开具体实现细节，Zola 内容库的核心结构可以抽象成两层字典。外层键是 path，内层是语言到内容的映射。把逻辑抽出来大概是这样：
// 逻辑示意，非源码原文 type Library = HashMap<String, HashMap<String, Content>>; fn insert(&mut self, path: String, lang: String, content: Content) { self.0 .entry(path) .or_default() .insert(lang, content); }每次读到一个 Markdown 文件，就解析出(path, lang)这对坐标，然后往这个嵌套字典里塞。塞完所有文件，整个内容库就成型了。所谓“翻译关系”，本质上就是内层字典里 key 的集合——如果有zh和en两个 key，说明这对翻译齐全；如果只有zh，那就是未翻译。
这个结构解释了为什么 Zola 对命名如此敏感：没有额外的人工对齐步骤，只有这一层自动归并。归并不上，后面所有环节都拿不到关系。
插入顺序在这里也有影响。文件遍历顺序和处理顺序决定了同键冲突时谁覆盖谁，这一点下一小节展开。
3.2 覆盖与冲突：同 lang 同 path 的两份文件
如果出现两份能被解析成同一(path, lang)的文件，会发生什么？比如content/blog/a.md（默认语言）和content/blog/a.zh.md，而zh恰好就是默认语言。这时两份文件的 path 都是blog/a，lang 也都是 zh，内层字典里同一个 key 被写了两次。
Zola 的处理策略是后者覆盖前者（具体哪个算后者取决于遍历顺序），并且通常会在构建日志里提示。这个提示很容易被淹没在一堆输出里，所以我的习惯是每次加完新内容都扫一眼构建输出里的 warning，看到路径重复一定停下来查。
冲突更隐蔽的变体是：content/blog/a.md和content/blog/a.en.md，而默认语言不是en。这样内层字典里会有default和en两个 key，看起来一切正常，但如果你本意是让a.md当英文版，实际却生成在根路径下、被标记成默认语言，英文站的translations里根本找不到它。这种“看起来分组成功但语义错位”的问题，只能靠统一命名规范来防。
我的做法是：除了极少数纯默认语言内容，其余全部显式带语言后缀，包括默认语言。也就是默认语言的页面也叫a.zh.md，不写裸文件名。多打四个字符，换来的是“每份文件的语言归属一眼可见”，长期看非常划算。
3.3 模板侧 translations 的构造过程
模板里用的translations，是在渲染阶段从内层字典里现场构造出来的。给定一份内容，先拿到它的 path，去外层字典里取出对应的内层字典，然后把该字典里除自己以外的所有条目转换成模板可用的结构，通常包含语言代码和该语言下的永久链接。
这个过程有两个必须记住的特征。
第一，translations只包含已经存在的内容，不包含“应该有但还没有”的语言。所以它天然是一个“已翻译清单”，不是“应翻译清单”。想判断某篇内容缺哪些语言，得反过来用：遍历config.languages，看每个语言代码是否出现在translations的语言集合里，差集就是缺的。
第二，translations里的链接是那条内容自己的永久链接，不是当前页面的语言切换链接。很多人在语言切换器里直接遍历它，结果发现当前语言没有对应项——因为自己那个条目被排除了。正确做法是先渲染当前语言，再遍历translations补充其他语言。
模板里大致长这样：
<nav class="lang-switch"> <span class="current">{{ lang }}</span> {% for t in page.translations %} <a href="{{ t.permalink }}" hreflang="{{ t.lang }}">{{ t.lang }}</a> {% endfor %} </nav>如果某个语言完全没有这篇的翻译，这里就不会出现它的入口。对多数站点来说这正是期望行为，但也意味着未翻译内容在导航层是彻底不可见的——用户从英文首页点进某篇文章，切换器里只有英文，想找中文版得自己回首页。这个体验是否可接受，取决于你的站点定位，下一节讲怎么按需处理。
4. 搭骨架：从配置到模板的可运行最小样例
4.1 config.toml 里的语言声明
语言必须在配置里显式声明，否则一切文件名约定都是空谈。最小配置大概是这样：
base_url = "https://example.com" default_language = "zh" compile_sass = true build_search_index = true [languages.zh] title = "某技术博客" generate_feed = true taxonomies = [{ name = "tags" }] [languages.en] title = "Some Tech Blog" generate_feed = true taxonomies = [{ name = "tags" }]几个容易忽略的点：
default_language决定根路径内容的归属，也决定一部分默认行为的落点。把它设成站点主要受众使用的语言，别因为习惯就设成英文。
每个语言的taxonomies必须分别声明。很多人只在顶层写了一行也行，但一旦要给某语言加独立分类，就得写在这层。漏了的话，该语言的标签页面不会生成，页面上会出现一堆指向不存在地址的链接。
generate_feed是按语言分别生效的，每种语言的 feed 只包含该语言内容。如果发现英文 RSS 里混着中文文章，基本可以断定是模板里手动拼了全站页面列表，绕过了语言过滤。
4.2 目录结构与文件命名
一个双语博客的实际骨架，我会这么组织：
content/ ├── _index.zh.md ├── _index.en.md ├── about.zh.md ├── about.en.md └── blog/ ├── _index.zh.md ├── _index.en.md ├── rust-notes.zh.md ├── rust-notes.en.md ├── zola-i18n.zh.md └── zola-i18n.en.md注意_index.zh.md里也要有内容，哪怕只是标题和一段摘要。它是 section 的语言载体，缺了它，该语言的列表页get_section拿不到东西。
对于暂时不想翻译的页面，我的处理是：先建一个占位文件，front matter 里写draft = false但正文只放一句“本文暂无该语言版本”，同时在 front matter 里加个自定义字段标记状态。这样做的好处是分组关系先建立起来，语言切换器能正常跳转，不会出现“点击后 404”；代价是搜索引擎可能收录这篇占位页，所以要在模板里对这类页面加noindex，或者干脆把它们排除在 sitemap 之外。
4.3 语言切换器与缺失降级
单纯的translations循环只能覆盖“已翻译”的情况。想让缺失时有优雅降级，得组合三个信息：当前页面 path、全站语言列表、当前页面的翻译集合。
{% set all_langs = config.languages %} {% set translated = page.translations | map(attribute="lang") | concat(with=[lang]) %} <nav class="lang-switch"> {% for code, conf in all_langs %} {% if code in translated %} {% if code == lang %} <span aria-current="true">{{ conf.title }}</span> {% else %} {% for t in page.translations %} {% if t.lang == code %} <a href="{{ t.permalink }}">{{ conf.title }}</a> {% endif %} {% endfor %} {% endif %} {% else %} <a href="{{ get_url(path='') }}" class="disabled" title="该语言暂无此页">{{ conf.title }}</a> {% endif %} {% endfor %} </nav>这段模板的价值在于把“未翻译”从不可见变成可见且可解释。用户看到另一种语言是灰的，鼠标悬停提示“暂无此页”，心里有数；点进去回到该语言首页，比 404 友好得多。
get_url(path='')的写法依赖于你的语言根路径配置。如果语言采用子路径（/en/）承载，这样写会自动指向该语言首页；如果用独立域名，需要在配置层处理，模板侧改用一个统一入口变量会更省事。
4.4 词条、日期与排序的本地化细节
界面上的固定文案，比如“”“发表于”“标签”，属于另一种意义上的“未翻译内容”。它们不在 Markdown 里，而在模板里，所以做文件差集查不出来。Zola 提供了词条表机制，在语言配置下写translations表：
[languages.en.translations] read_more = "Read more" published_on = "Published on" tag_label = "Tag"模板里用{{ trans(key="read_more") }}取。缺失的词条会回退到默认语言，所以如果你只翻译了一半，英文站会突然冒出几个中文词——这种“半截翻译”在页面上非常刺眼。我的习惯是：加新词条时，一次性把所有语言的配置都补上，哪怕暂时是机翻加个待审标记，也比留空好。
日期格式同理。Tera 的日期过滤器需要显式指定格式串，不同语言的月份名和日期顺序不一样，硬编码一个"%Y-%m-%d"虽然能跑，但中文站显示2024-05-01、英文站也显示2024-05-01，读者体验就那样。想本地化，得在模板里按lang分支，或者用各语言自己的格式串配置项。
排序也是个隐藏坑。列表页按date排序时，如果某篇文章的英文版日期和中文版日期不同（这在分批翻译时很常见），两个语言站的文章顺序会不一致。是否有问题取决于站点类型，但至少要意识到这件事，别等用户反馈“你们英文站的顺序怎么和中文不一样”。
5. 分级处理：不同站点的不同取舍
5.1 全量翻译站的严格模式
内容量不大、翻译能力稳定的站点，最省心的策略是严格模式：任何一篇内容，所有语言版本必须齐全，缺一不可。落地手段是在构建前跑一个自检脚本，比对各语言目录下的文件名集合，发现差集就退出非零码，让 CI 拦住这次发布。
严格模式的代价是发布节奏被翻译进度绑架。缓解办法是把“必须齐全”的范围缩小——只对核心页面（首页、关于、产品介绍、定价）做严格校验，博客文章允许滞后，但需要在列表页对未翻译文章做标记处理。
我在一个只有十几页的站点上用过严格模式，效果很好：半年下来没有一次因为漏翻上线。但在日更博客上用就完全不现实，那属于跟自己过不去。
5.2 部分翻译站的降级模式
内容多、翻译跟不上的站点，我的建议是降级模式，分三层处理。
第一层，列表页展示所有语言的内容，但标注原文语言。中文站的列表里，英文文章标题后面挂个EN角标，点进去看到的是原文，页面顶部有一条横幅“本文暂无中文版本，以下为英文原文”。这条横幅的文案本身要尽可能翻译得准确，因为它是用户此刻唯一能看懂的引导。
第二层，导航和侧边栏只展示当前语言已有的条目。这个用translations判断即可，缺翻译的条目在导航里隐藏。降级不等于到处留空洞，主导航应该干净。
第三层，搜索索引按语言隔离。每种语言只索引自己语言的内容，中文站搜不出英文文章。这条最容易被忽略，因为搜索索引是构建期生成的，出问题不报错，只在用户搜索时表现为“搜出来的东西看不懂”。
5.3 共享型页面与“伪翻译”处理
有些页面天然不需要翻译，比如图片墙、代码片段库、外链收藏。给它们每种语言都建一份一模一样的文件，维护成本翻倍还容易不同步。
处理思路是只建默认语言版本，其他语言用跳转或重定向承接。具体做法是在目标语言的对应路径放一个极简的 Markdown，正文只放一段说明加一个链接指回默认语言版本；或者在模板层给这类页面单独开一个布局，直接渲染默认语言的数据。
另一类是伪翻译：内容其实一样，只有标题和描述做了本地化。这类页面对 SEO 有价值，但要小心别让用户在两种语言间来回跳转看到完全相同的内容，那体验很怪。我的做法是在页面顶部用词条标注“以下内容为通用资料”，说清楚比藏着好。
还有一种极端情况：某个语言的内容量少到不足以支撑独立站点，比如只有两篇文章。这时候与其硬开一个语言站，不如把这两篇直接以原文形式放在默认语言站里，加个语言标注。开一个只有两页的站点，维护成本远大于收益。
6. 排查实录：构建不报错但线上出问题的那些场景
6.1 常见问题速查表
下面这张表是我这几年攒下来的，按“症状 → 最可能原因 → 验证手法”组织。遇到问题先对表，比从头读源码快得多。
| 症状 | 最可能原因 | 验证手法 |
|---|---|---|
| 某语言列表页为空 | 对应_index缺该语言版本 | 检查该目录下是否存在_index.<lang>.md |
| 语言切换器里少了某语言 | 该内容缺该语言版本，或 path 不一致 | 对比两份文件去后缀后的路径字符串 |
| URL 里出现奇怪的语言段 | 语言代码未在配置声明，被当成文件名 | 检查[languages]下是否有该代码 |
| 同一页面生成两份 | 裸文件名与带后缀文件 path 冲突 | 看构建日志里的重复路径警告 |
| 标签页混入其他语言内容 | get_taxonomy未传lang | 在模板里打印实际传入的参数 |
| 英文 RSS 里有中文 | feed 模板手动拼了全站页面 | 检查 feed 模板是否遍历section.pages |
| 搜索出现其他语言结果 | 索引未按语言隔离 | 检查搜索配置与索引生成路径 |
| 翻译关系时有时无 | 文件名大小写不统一 | 统一小写，部署到敏感环境复现 |
表格只能覆盖高频项，真正难缠的是“看起来都对但就是不对”的情况，那基本要靠打日志。
6.2 构建期自检脚本
比事后排查更划算的是事前拦截。我习惯在构建前跑一个小脚本，做三件事：找缺失、找多余、找路径冲突。
#!/usr/bin/env bash set -euo pipefail LANGS=("zh" "en") ROOT="content" # 收集每个语言的文件集合（去掉语言后缀后的相对路径） for l in "${LANGS[@]}"; do find "$ROOT" -name "*.$l.md" \ | sed -E "s/\.$l\.md$//" \ | sort > "/tmp/zola-$l.txt" done # 两两求差集，输出缺失情况 for l in "${LANGS[@]}"; do for m in "${LANGS[@]}"; do [ "$l" = "$m" ] && continue echo "== 存在于 $l 但 $m 缺失 ==" comm -23 "/tmp/zola-$l.txt" "/tmp/zola-$m.txt" || true done done这段脚本刻意保持简单，因为它要能塞进任何 CI 环境。想更严格的话，可以在差集非空时直接exit 1，把“允许缺失”的白名单写进一个单独的文件，脚本里过滤掉。
需要说明的是，这套逻辑只处理显式带语言后缀的文件。如果你有裸文件名存在（默认语言），得先把它们也归到默认语言集合里，否则会误报一堆“缺失”。
6.3 几个我踩过的具体坑
坑一：加语言时忘了改base_url相关的模板逻辑。新增语言后，get_url生成的路径变了，但模板里有些地方硬编码了绝对路径，语言切换器指向了错误位置。教训是：任何涉及 URL 的地方都用get_url或内容自带的永久链接，别手拼。
坑二：把 taxonomy 的_index忘了。标签页的_index也需要语言版本。我一度以为标签是自动生成的不用管，结果英文站的标签页打开是空的。补上content/tags/_index.en.md之后才正常。这个文件本身内容可以极简，但必须存在。
坑三：草稿状态不同步。中文版已经发布，英文版还挂着draft = true。这种情况下英文站的translations里不会包含中文版，分组直接断掉，语言切换器少一个入口，但文章在中文站正常。这种“一边发布一边草稿”的状态最难自查，只能靠发布清单核对。
坑四：分页参数在两种语言下不一致。中文站paginate_by = 10，英文站忘了写，用默认值。结果两边分页数量不同，sitemap 里的分页 URL 对不上，做 hreflang 标注时全是错位。这类配置最好提到顶层或者用一致的模板变量，别在 section 的 front matter 里各写各的。
坑五：重命名文件后翻译关系断裂。把old-name.zh.md改成new-name.zh.md却没改英文版，两份 path 不同了，配对失效。这个错误在人眼里是“我明明改了名”，在程序眼里就是两个不相干的东西。改名前先确认两边都改，或者干脆两篇一起重命名。
提示：重命名内容文件时，务必成对操作。Zola 不会因为你改了中文文件名就自动更新英文版的配对关系，它只认最终 path 是否相等。
真的要说经验的话，未翻译内容这件事的解法不在技术细节里，而在流程约束里。把“新增一篇内容必须同时建立所有语言的占位文件”写进自己的操作习惯，比任何排查脚本都管用——脚本能告诉你缺了什么，但只有流程能让它不缺。我现在的做法是新建内容时先复制一份空壳到每个语言目录，正文哪怕只有一句“待补”，path 先对齐了，后面填内容就只是填空。这个习惯一开始觉得啰嗦，用上两个月就回不去了，因为你再也不会在半夜收到“你们英文站的某个链接点开是 404”这种消息。
