-
Notifications
You must be signed in to change notification settings - Fork 65
开始翻译
由于 WHATWG/html 作为 Living Standard 更新迅速，完全的同步翻译非常困难。 我们欢迎任何形式的参与，包括校对纠错、更新增补、术语讨论等。如果希望提供（或更新）一篇翻译，可参考下列操作步骤：
- 为了避免重复工作，请先发起 Issue。指明你要翻译的章节，如
翻译 1.2.13- Clone本仓库至本地
git clone git@github.com:whatwg-cn/html.git --depth=1- 在src下更改或新增一篇文档，以
xxx.zh.html命名。例如：
# 更新一篇中文文稿
vim src/xxx.zh.html
# 创建一篇中文文稿
cp src/xxx.en.html src/xxx.zh.html- Push 你的代码到对应分支，如：translation-1.2.13
- 发起 Pull Request 到
master分支（注意不要提交output/下的改动）
至此你可以开始行动了！但我们建议你继续阅读下文的具体的建议和指导，可以帮助你理解源文件并更快地翻译。
这些 *.en.html, *.zh.html 文件并非合规的 HTML 文件，而是用于产生 HTML 的文件碎片。
因此请保持原有缩进和标签省略方式，注意行尾空格会产生编译错。
此外请使用中文标点，以及中英混排请添加空格。
本项目的维护原则是尽可能最新，不基于某个固定版本进行翻译。 这样可以确保每次一部分时都可以基于最新的原文来翻译，可能的问题是不同部分之间新旧不一，有些引用会失效。 因此如果被引用的术语不存在了，可以直接把 data-x 和 span 去掉。
引用定义过的术语时，该引用会显示为超链接（<a>标签），指向术语定义的文档以及锚点。
当前的HTML标准中有4000+处术语定义。术语定义有两种方式：
<!--定义术语：the HTML syntax-->
<dfn>the HTML syntax</dfn>
<!--定义术语：attr-id-->
<dfn data-x="attr-id">ID属性</dfn>对应地，术语引用也有不同的方式：
<!--引用术语：the HTML syntax-->
<span>the HTML syntax</span>
<!--引用术语：attr-id-->
<span data-x="attr-id">ID属性</span>可见，通过data-x属性可以实现术语定义（或引用）的实际名称与显示名称不同。
我们借此特性来翻译术语，不允许改变术语的实际名称。例如我们将：
<dfn>the HTML syntax</dfn>翻译为：
<dfn data-x="the HTML syntax">HTML 语法</dfn>这样可以不破坏既有的对"the HTML syntax术语的引用。
在 HTML 标准的编写过程中，有些 HTML 标签和属性被赋予特殊的语义，使用时要遵守既有约定。
-
dfn：定义一个属于，如果希望显示名称和定义 ID 不同，添加值为术语 ID 的data-x属性。 -
code,span：显式属于引用，其内容对应术语 ID。如果希望显示名称与引用 ID 不同，添加值为术语 ID 的data-x属性。 -
i：表示强调，不会被解析为术语引用。 -
var：表示变量名，一般不需翻译，不会被解析为术语引用。 -
data-x：定义或引用的术语 ID，如果置空表示这一标签不引用也不定义任何术语。 -
data-export：导出术语，值总是空字符串。
例如下面的 code 不引用任何术语：
<code data-x="">&</code>译注 是翻译版本中增加的一种格式，用于补充说明由于语言或文化差异引起的翻译困难。 但我们建议尽量通过合适的翻译来表达清楚，不建议随处添加译注。也欢迎发起 Issue 来讨论。 译注的格式如下：
<p class="comment">这里是你希望增加的翻译注释……</p>如果你熟悉 Node，或熟悉 Vim，可以试着用用这些工具：
-
./bin/translate-references.js根据 dfn.json 自动翻译术语，是一个 formatter，STDIN 读入内容，STDOUT 输出。 -
.vimrc提供了翻译标点、常见语法（不一定好使）的快捷键，翻译术语（一定好使）的快捷键和 Autoformat 插件。