翻译

站点可以用多种语言发布。第一种语言是默认语言，保留原有 URL；其他每种语言都在自己的前缀下提供，例如 /es/，并拥有自己的导航、搜索、llms.txt 和界面文字。页眉会出现语言选择器，尚未翻译的页面仍保留在导航中，并标注其所用的语言。

配置语言

languages:
  - code: en
    label: English
  - code: es
    label: Español
  - code: zh
    label: 简体中文

每种语言接受：

没有 languages 时，站点只有英语一种语言，下文内容均不适用。重复列出的代码、未知的消息键，或前缀位于另一种语言前缀之下（/es/…）的分区，都会导致构建失败。

翻译页面

译文是位于原文旁边的文件，在 .html 之前加上语言代码命名。它在该语言的前缀下提供，并按 URL 与原文配对：

不对应任何已配置语言的后缀仍是文件名的一部分，因此 vite.config.html 依然是英语页面。若要把译文放在单独的文件夹中，或自由命名文件，可以改为在其 head 中设置语言；已经位于该语言文件夹下的文件不会被重复加前缀：

<meta name="language" content="es" />
<meta name="path" content="/guides/install/" />

---
language: es
path: /guides/install/
---

只有当译文与原文在语言前缀之下共享同一个 URL 时，两者才会配对，所以要给重命名的文件设置与原文相同的 path。配置中未列出的语言会导致构建失败。

翻译配置

站点的 title、description 和 banner，链接的 title，以及分区的 title、 siteTitle 和 siteDescription，既可以接受一个适用于所有语言的文本，也可以接受按语言代码组织的映射。映射中缺少的语言使用默认语言的文本：

title:
  en: Acme Docs
  es: Documentación de Acme
sections:
  - title: { en: Guide, es: Guía, zh: 指南 }
    prefix: /
  - title: Blog
    type: blog
    prefix: /blog/

每个分区以及每个带有 prefix 的链接都会在每种语言的前缀下镜像一份：西班牙语博客位于 /es/blog/，拥有自己的索引、标签页面和 RSS 订阅源，先列出西班牙语文章，再列出尚未翻译的默认语言文章。变更日志分区会在每种语言中构建其页面，发布说明保持原文；这些副本的规范 URL 指向默认语言的版本，并且不列入 sitemap。若 custom 分区的 url 指向站点内的页面，且当前语言有该页面的翻译，则会链接到该翻译。

尚未翻译的页面

每种语言都会列出所有尚无译文的默认语言页面，使其导航保持相同的结构。这类条目链接到原文，并以徽章形式显示默认语言的代码，悬停提示为"尚未翻译"。未翻译的页面只以其原有语言构建一次；搜索和 llms.txt 只列出该语言自己的页面。

语言选择器把每种语言链接到当前页面在该语言中的版本，否则链接到该语言的首页。没有自己首页（index.es.html）的语言，会获得一个从 /es/ 到其第一个页面的重定向；没有 index.html 的默认语言也是如此。读取 _redirects 的托管平台（如 Cloudflare 和 Netlify）以及 htmlpress start 会在服务器端重定向；其他平台则使用重定向页面。

界面文字

Htmlpress 自身的文字，例如 "On this page"、"Previous" 和 "Edit this page"，以及日期，内置了英语、德语、西班牙语、法语、日语、俄语和中文版本，按 locale 的语言选择。其中任何一项都可以按语言替换：

languages:
  - code: en
    label: English
    messages:
      page.edit: Edit on GitHub
  - code: pt
    label: Português
    locale: pt-BR
    messages:
      toc.title: Nesta página
      nav.previous: Anterior
      nav.next: Próximo

对于 htmlpress 未内置的语言，未设置的文字会回退到英语。可用的键见 messages/en.yaml；{date} 这类 {name} 占位符会被填充。 date.format 和 date.months 决定了向读者显示的每个日期的格式。

翻译页面会获得什么

• <html lang>，以及对于从右到左书写的语言， <html dir="rtl">。
• 设置了 site 时，为每种拥有该页面的语言生成 hreflang 备用链接，另加指向默认语言版本的 x-default，以及一个 og:locale。
• 该语言的搜索索引 _htmlpress/search.<code>.json，以及位于该语言前缀下的 Markdown 副本和 llms.txt。
• <htmlpress-language> 选择器，弹出的布局可以像放置其他元素一样放置它；在单语言站点上它会被移除。

另请参阅

• 配置： htmlpress.yaml 的所有键。
• 文章分区：前缀和分区匹配的工作方式。
• Frontmatter：页面自身的元数据，包括 <meta name="language">。