# 翻译

> 以多种语言发布站点，带有语言选择器、已翻译的界面文字，以及为尚未翻译的页面提供的回退。

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

## 配置语言

**htmlpress.yaml**

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

每种语言接受：

| 字段         | 默认值                            | 用途                                           |
| ---------- | ------------------------------ | -------------------------------------------- |
| `code`     | 无，必填                           | URL 前缀和文件名后缀：由小写字母、数字和 `-` 组成，以字母开头。         |
| `label`    | 无，必填                           | 语言选择器中显示的名称。                                 |
| `locale`   | `code` 的值                      | 用于 `<html lang>`、hreflang 和日期的标签，例如 `pt-BR`。 |
| `dir`      | 阿拉伯语、希伯来语、波斯语、乌尔都语等少数语言为 `rtl` | `ltr` 或 `rtl`，写入 `<html dir>`。               |
| `flag`     | locale 中的地区，否则为该语言通常对应的国家      | 选择器中旗帜所用的两字母国家代码，例如 `br`；没有内置旗帜的代码不显示旗帜。     |
| `messages` | 无                              | 替换内置文字的界面文字；见下文。                             |

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

## 翻译页面

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

- index.html — `/`

- index.es.html — `/es/`

- guides

  - install.html — `/guides/install/`
  - install.es.html — `/es/guides/install/`

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

**HTML**

**es/guias/instalar.html**

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

**Markdown**

**es/guias/instalar.md**

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

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

## 翻译配置

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

**htmlpress.yaml**

```yaml
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 的语言选择。其中任何一项都可以按语言替换：

**htmlpress.yaml**

```yaml
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`](https://github.com/datisthq/htmlpress/blob/main/rust/src/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>` 选择器，弹出的布局可以像放置其他元素一样放置它；在单语言站点上它会被移除。

## 另请参阅

- [配置](/zh/customization/configuration-file/)： `htmlpress.yaml` 的所有键。
- [文章分区](/zh/customization/article-sections/)：前缀和分区匹配的工作方式。
- [Frontmatter](/zh/authoring/frontmatter/)：页面自身的元数据，包括 `<meta name="language">`。