文档翻译格式 (Translation Spec)

文档翻译格式（中英文位置等）

请注意：请不要修改原始英文文档的结构，以避免全球英文文档更新时额外的工作量。

参见样本和注释

https://gist.github.com/chenglu/87c3743b37ccb193df57544c4a082f20

图示（常见翻译格式）

翻译语法

markdown 标题、段落等

直接把中文放在原文下方即可：

## english

## 中文

english

中文

markdown 列表（-、*、1. 等）

中文要换行并且缩进要与文字部分对齐

- one

  一
  
- two

  二
  
- three

  三

注意：不要省略中间和末尾的空行。

markdown 表头/其它内容

对原有内容套上 标签，如：

<t>one</t><t>一</t> | <t>two</t><t>二</t> | <t>three</t><t>三</t>
----|----|----
four | five | six

markdown 表体

在紧下一行书写中文（可任意添加空格进行对齐），如：

<t>one</t><t>一</t> | <t>two</t><t>二</t> | <t>three</t><t>三</t>
----|----|----
four | five | six
四    | 五   | 六

HTML 内容 - 容器型块元素

对于内嵌在 md 中的 html 内容，需要特殊处理

h\d|p|header

可以直接在下方放中文，如：

<p>
english
</p>

<p>
中文
</p>

内容不限

div

可以直接在下方放中文，但只支持单行，如：

<div>english</div>

<div>中文</div>

但不支持：

<div>
english
</div>

<div>
中文
</div>

span|a

可以直接在紧后方放中文，如：

<span>english</span><span>中文</span>

中间换行也可以。但尽量不要用这种方式，而是优先使用整段翻译的方式。

ol|li

一般原文会以下面这种形式出现：

<ol markdown="1">
<li markdown="1">

english...

</li>
</ol>

直接在标签体内，换行将英文放在原文下方：

<ol markdown="1">
<li markdown="1">

english...

中文...

</li>
</ol>

dl|dt|dd

一般原文会以下面这种形式出现：（当文本中含 md 格式时，标签会含有 markdown="1" 标识）

<dl markdown="1">
<dt markdown="1">english</dt>
<dd markdown="1">english</dd>

此时，需要将原文使用 p 标签包裹，并且下方的中文依然使用 p 标签包裹（如果文本中包含 md 格式的标签，需要在 p 标签中标识 markdown="1"），如：

<dl markdown="1">
<dt markdown="1">
<p markdown="1">english</p>
<p markdown="1">中文</p>
</dt>
<dd markdown="1">
<p markdown="1">english</p>
<p markdown="1">中文</p>
</dd>

这里的被 p 标签包裹的英文和中文可换行也可不换行，为了方便阅读，建议原文和译文分属不同行。

特别注意

文档中的「您」请使用「你」，以表示与开发者平等沟通的意味。

当翻译时文档中有类似：

链接
: 说明

即冒号在一行的最前面这种格式的，请将 : 换成 <br> （包括原文）。

常见问题

目录中没有出现正文中的分级标题或者依旧是英文

如果遇到分级标题没有出现在目录中（右侧或顶部）， 或者翻译后目录中依然是英文的情况。

例如，正文中有如下标题：

## English

## 中文

但是目录中依旧是 English。

解决方式是对中文翻译的后方添加一个唯一的锚点。

Note

中文后面的锚点内容不重要，最终都会被替换为英文部分的锚点，
目的是让锚点在本页内处于唯一值并通过站点生成器的检查。

更改如下：

## English

## 中文 {:#中文}

或者

## 中文 {:#1}

如果 CI 中报如下错误，同样也是因为标题的锚点不唯一，无法通过检查。
只需要按照上面的方式为中文标题添加一个唯一的锚点。