静态站点CLI开发工具【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址https://gitcode.com/GitHub_Trending/zo/zola点击查看免费下载在 Zola 中多语言站点的骨架由content目录里的_index.md默认语言 Section与_index.{code}.md翻译版 Section共同构成站点首页就是最典型的一个 Section。本文以仓库中的多语言测试站点 test_site_i18n 为研究对象从它的首页文件_index.md出发完整讲解 Zola 如何通过文件名识别语言、如何为每个语言编写首页 Section、/内部链接与自定义锚点的写法以及构建后每种语言在 URL、搜索索引、Feed 和分类上的独立行为。读完本文你将能独立搭建一个像example.com/fr/、example.com/it/这样按语言分目录输出的多语言 Zola 站点。一、起点默认语言首页_index.md到底长什么样多语言测试站点的默认语言首页文件位于 test_site_i18n/content/_index.md全文如下 title Home Homepage. [Our blog](https://link.gitcode.com/i/9a81ffdf54f359f3bb0b449976a4fd0f)这个文件本身很小但它浓缩了 Zola 多语言站点的三个关键事实TOML front matter以包裹title即该 Section首页的标题默认语言下不需要在文件名里标注语言代码/内部链接语法[Our blog](https://link.gitcode.com/i/9a81ffdf54f359f3bb0b449976a4fd0f)中的/表示从content目录开始的绝对内容路径链接目标直接指向content/blog/_index.md这个博客 SectionSection 即语言分组的边界默认语言的所有页面含首页共享en语言标记而每种语言的首页 Section 是独立的对象。同级目录下还有它的法语版 test_site_i18n/content/_index.fr.md title Accueil Page daccueil. [Notre blog](https://link.gitcode.com/i/f488969146e1ebccec6cd8f8839155aa) [Lire notre description](#about) # À propos {#about}对比两个文件可以立刻看出多语言写作的两条规则同语言的内部链接指向同语言的文件/blog/_index.mdvs/blog/_index.fr.md以及可以用{#about}为标题手动指定锚点 id再用[Lire notre description](#about)做页内深链。二、语言从哪来文件名后缀的解析规则Zola 用文件名来判定内容语言这是多语言机制的核心约定。官方文档 multilingual.md 明确给出的规则是content/an-article.md默认语言content/an-article.fr.md法语文件名中的语言代码如果既不在config.toml的[languages]中、也不等于default_language构建会直接报错。该逻辑在源码 components/content/src/file_info.rs 的find_language中实现。它先按第一个.把文件名切分为name与语言代码两部分源码注释明确假定启用 i18n 时文件名不使用.未配置任何其他语言时直接返回默认语言文件名没有.时返回默认语言语言代码与default_language相同时仍归为默认语言语言代码不在配置中时抛出错误信息File {:?} has a language code of {} which isnt present in the config.toml languages。该函数的单元测试覆盖了python.fr.md → fr、python.en.md → en、未知语言报错、以及 Section 文件_index.fr.md等场景见 file_info.rs 测试段。三、没有语言回退每个语言都要有自己的_index.{code}.md这是多语言站点最容易踩坑的一点。官方文档 multilingual.md 特别强调如果默认语言在一个目录下有_index.md那么你需要为每种语言额外提供_index.{code}.md因为 Zola 的 Section没有语言回退no language fallback。也就是说_index.fr.md、_index.it.md不会自动继承_index.md的 front matter。测试站点中test_site_i18n/content下只有_index.md与_index.fr.md两个首页文件、没有_index.it.md这意味着意大利语版首页需要自行补充才能得到与默认语言一致的 Section 配置。在源码层面components/content/src/library.rs 按语言预构建了 Section 文件名映射for code in config.languages.keys() { if code config.default_language { index_filename_by_lang.insert(code, _index.md.to_owned()); } else { index_filename_by_lang.insert(code, format!(_index.{}.md, code)); } }从这段代码可以推断Section 的发现完全依赖这套「默认语言用_index.md、其他语言用_index.{code}.md」的命名规则这也是为什么每种语言都必须显式提供自己的 Section 文件。四、在 config.toml 中声明语言并配置每语言特性要让上面的文件结构生效必须在配置文件里声明语言。test_site_i18n/config.toml 是一个完整的真实示例base_url https://example.com default_language en generate_feeds true taxonomies [ {name authors, feed true}, {name tags}, ] [search] include_title true include_description true include_path true include_content true [languages.fr] generate_feeds true taxonomies [ {name auteurs, feed true}, {name tags}, ] [languages.it] build_search_index true关键配置项说明配置项作用本测试站点取值default_language站点默认语言默认值为en用于 Feed 等场景en[languages.{code}]每个语言的独立配置节fr、it[languages.{code}].generate_feeds是否为该语言生成 Feedfr trueit 未开启[languages.{code}].taxonomies该语言专属的分类定义fr 用auteurs默认语言用authors[languages.{code}].build_search_index是否为该语言构建搜索索引it truefr 未开启官方配置文档 configuration.md 指出[languages]下可以覆盖title、description、generate_feeds、feed_filenames、taxonomies、build_search_index还可以定义语言自己的搜索配置与[translations]翻译项。注意默认语言的配置写在主层级如taxonomies、[search]而非[languages.en]下从源码 config/mod.rs 的add_default_language可以确认构建时系统会把主层级的配置复制为默认语言的基础配置再按需合并[languages.{default}]中的覆盖项。另外官方多语言文档还提示中日文搜索索引默认不包含需要以cargo build --features indexing-ja --features indexing-zh方式启用且开启后二进制体积会显著增大中文约增加 5 MB、日文约增加 70 MB源于大型词典。五、/内部链接跨语言与锚点深链首页里出现的[Our blog](https://link.gitcode.com/i/9a81ffdf54f359f3bb0b449976a4fd0f)使用了 Zola 专有的内部链接语法。官方文档 linking.md 说明以/开头、指向content目录下的.md文件即可例如content/pages/about.md写作my link可以带锚点my link会直接跳到该页面对应标题/同样适用于解析同目录资源asset colocation默认情况下失效的内部链接按错误处理若在[link_checker]中设internal_level warn则降级为警告此时失效链接会原样渲染为a href/pages/whoops.md。跨语言场景下链接必须指向同语言的内容文件这正是_index.fr.md里写/blog/_index.fr.md的原因。此外首页还可以用#前缀做页内锚点链接如法语版的[Lire notre description](#about)配合# À propos {#about}这种手动指定 id 的写法可以让深链在标题文字日后修改时保持稳定——该机制也用于站点迁移时保留旧标题的锚点 id。六、构建产物每种语言一个独立 URL 前缀Zola 会以{base_url}/{code}/作为各语言的基准 URL 输出内容唯一的例外是在 front matter 里为翻译页显式指定了path。测试站点base_url https://example.com因此法语内容输出到https://example.com/fr/。多语言构建测试 components/site/tests/site_i18n.rs 用大量断言验证了这一行为首页产物index.html与fr/index.html同时存在fr/index.html包含法语内容Une page与Language: fr翻译信息互链blog/index.html中会输出Translated in fr: Mon blog https://example.com/fr/blog/而fr/blog/index.html中反向输出Translated in en: My blog https://example.com/blog/站点地图覆盖所有语言sitemap.xml同时包含https://example.com/blog/something-else/、/fr/blog/something-else/与/it/blog/something-else/每语言 Feed 只含本语言条目atom.xml的xml:langen且不含法语 URLfr/atom.xml的xml:langfr、id指向自身未开启 Feed 的意大利语不生成it/atom.xml分类按语言隔离英语侧只有authors/与tags/hello法语侧只有auteurs/与tags/bonjour两者互不串台。测试站点的首页模板 test_site_i18n/templates/index.html 展示了如何用 Tera 遍历section.translations输出各语言版本{% for page in section.pages %} {{page.title}} {% endfor %} Language: {{lang}} {% for t in section.translations %} Translated in {{t.lang|default(valueconfig.default_language)}}: {{t.title}} {{t.permalink|safe}} {% endfor %}其中lang变量即当前页面的语言代码section.translations的构建逻辑在 library.rs系统会读取每个内容文件的翻译姊妹文件基于canonical路径定位见 file_info.rs并填充其语言、永久链接与标题。七、每语言独立的搜索索引默认语言与各语言可以分别开关搜索索引。测试配置中[search]全局开启索引include_title、include_description、include_path、include_content均为true[languages.it] build_search_index true让意大利语也生成索引法语没有开启。测试can_build_multilingual_sitesite_i18n.rs验证了产物是按语言分文件的search_index.en.js与search_index.it.js且不生成search_index.fr.js。另一个回归测试can_build_search_index_for_non_default_language_onlysite_i18n.rs对应上游 issue #2689进一步证明即使把全局与英语的索引都关掉意大利语索引依然会独立生成——语言级配置与全局配置是相互独立的开关。八、从首页文件出发的完整落地清单对照test_site_i18n搭建一个多语言站点首页只需五步声明语言在config.toml中设置default_language并为每种语言添加[languages.{code}]配置节可含generate_feeds、taxonomies、build_search_index、[translations]等编写默认语言首页创建content/_index.md在 front matter 中给出title正文用/语法链接到本语言的子 Section 或页面为每个语言补写 Section创建content/_index.{code}.md如_index.fr.md记住没有语言回退front matter 需自行完整填写同语言互链翻译内容里的内部链接一律指向对应语言的文件/blog/_index.fr.md需要深链时用{#id}手动指定锚点并配合#id页内链接构建验证运行zola build后检查public/{code}/目录、sitemap.xml、各语言atom.xml与search_index.{lang}.js是否符合预期参考 site_i18n.rs 中的断言来对照验证。其中第 3 步是最容易遗漏的只要默认语言存在_index.md其余语言就必须补上对应的_index.{code}.md否则该语言将缺少可用的 Section 配置。赞分享静态站点CLI开发工具【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址https://gitcode.com/GitHub_Trending/zo/zola点击查看免费下载相关推荐Hugo 站点首页内容页实战从 Ananke 主题 _index.md 到 Vercel 静态构建全链路解析Hugo 站点首页内容页实战从 Ananke 主题 _index.md 到 Vercel 静态构建全链路解析 本文以 Vercel 仓库 packages/sCLI后端云原生Ananke 主题 _index.md 深入解析Hugo 站点首页 Front Matter 与 Vercel 部署实战Ananke 主题 _index.md 深入解析Hugo 站点首页 Front Matter 与 Vercel 部署实战 本篇技术指南以 Vercel 仓库中CLI后端云原生Zola 多语言站点中的未翻译内容从文件名约定到语言分组源码解析Zola 多语言站点中的未翻译内容从文件名约定到语言分组源码解析 Zola 是一个单二进制、内置全部功能的快速静态站点生成器其多语言i18n支持通过文件静态站点CLI开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
