Julia 中文文档翻译规范

[GaZ3ll3]

翻译规则

不可在英文原文基础上直接修改。 文档格式应保留为 .ｍｄ 。

• 翻译标题时， 应保留对应的级别。 比如， 二级标题翻译后也应是二级标题。 原标题应注释掉并放置在译好的标题下方， 以一个空行（或多个）分隔。

• 翻译正文时， 以段落为单位， 原文段落应以注释的形式放置在翻译好的段落下方， 以一个（或多个）空行分隔。 注意， 如果原文段落内含有代码， 也应注释掉， 并复制到对应的译文里。 注释时， 用 .. 开头， 这里的 .. 后有一个空格， 原文以一个 Tab 缩进。 例如：

定义新类型转换
~~~~~~~~~~~~~~

.. Defining New Conversions
.. ~~~~~~~~~~~~~~~~~~~~~~~~

要定义新类型转换，只需给 ``convert`` 提供新方法即可。 下例将数值转换为布尔值 ::

    convert(::Type{Bool}, x::Real) = x==0 ? false : x==1 ? true : throw(InexactError())

此方法第一个参数的类型是 :ref:`单态类型 <man-singleton-types>` ， ``Bool`` 是 ``Type{Bool}`` 的唯一实例。此方法仅在第一个参数是 ``Bool`` 才调用。

.. 
  To define a new conversion, simply provide a new method for :func:`convert`.
  That's really all there is to it. For example, the method to convert a
  real number to a boolean is this::

    convert(::Type{Bool}, x::Real) = x==0 ? false : x==1 ? true : throw(InexactError())

  The type of the first argument of this method is a :ref:`singleton
  type <man-singleton-types>`, ``Type{Bool}``, the only instance of
  which is ``Bool``. Thus, this method is only invoked when the first
  argument is the type value ``Bool``. 

• 由于Julia现在更换为了markdown作为文档语言，我们也更换到markdown．如果没有相对应的文件请直接复制英文版本过来．但暂时不要删除原来的.rst文件．

• 标准库目前先不做翻译。

• 所有的文档跟进官方repo的master分支。

• 对于表格， 如果翻译则请按照段落处理。

提交规则

• 提交译文时， 请用 pull request (PR) 提交。 对于翻译中不确定的部分， 请在 PR 里指明。

• 对于含有多个 commit 的 PR， 合并时， 请选择 squash and merge 。

书写规范

标点符号

中文内容请使用半角中文标点符号， 尤其是逗号以及括号， 冒号， 破折号。 对于引号， 如果被引用的内容包含英文， 则使用英文引号。

空格

译文一律使用空格， 禁止使用 Tab， 仅对注释原文时可以用 Tab 缩进， 缩进为两个空格。 中文和英文以及数字间应加一个空格。

粗斜体

中文部分不应使用斜体， 对于原文斜体部分， 译文里可以酌情修改为粗体。

内容规范

力求表达清楚明确， 语句尽量通顺， 请不要逐字翻译， 避免错别字等。

代码

只翻译注释， 如果代码简单易懂， 可不翻译。

专有名词

如果没有对应或者不确定的专有词汇， 可以先不译， 保留在译文里。 等确定后可批量修改。

人称代词

像 "we" 和 "you" 这些词汇一般来说可以不译出来， 或者换个说法。 如果译出来更通顺， 就翻译出来。

[GaZ3ll3]

如果有好的建议， 我们整合进来。 参考 http://docutils.sourceforge.net/docs/user/rst/quickref.html

可以设置一个wiki， 或者在 readme 里注明。 @wlbksy

如果可能的话， 需要一个脚本检测标点符号是否误用。

[Roger-luo]

@GaZ3ll3 在Readme里给一个这个issue的链接吧，方便新人找到这个issue。或者写一个guide之类的东西？

以及看到i18n里有人用gettext.jl辅助翻译，不知道我们用不用的上。

[Roger-luo]

现在要更新的１．０了，我们manual的翻译直接跟进master吧

[metaCoder-00]

我觉得 要不注释原文也采用4个空格的缩进。。。

[Roger-luo]

我觉得在markdown里没必要缩进啊

[metaCoder-00]

好的 那在md里面就不缩进注释原文了？

[Roger-luo]

我觉得没必要缩进，因为markdown里缩进的意义和rst不一样

[sunoru]

文档中出现的外部链接是不是也可以统一一下？比如有的维基百科链接我在翻译时全都改成了相应中文的页面链接，但好像有另外的人觉得中文维基现在上不去所以就保留了英文链接。

还有比如这个文档里的 Resources 部分，这些链接指向的是教程，需要把他们的名字翻译出来吗？

[Roger-luo]

这里这样翻译怎么样:

资源 (英文资源)

英文原文

然后后面我们自己加上一些中文资源(这个现在其实有不少人写了blog的)

[sunoru]

嗯嗯，同意，我就是想最好能统一一下如果别人在翻译别的页面也遇到这种地方了可以作为参考。

不过因为后面到时候可以加上中文资源，这个标题还是就不加这个括号了吧，像我的 pr 里这样可以嘛
#70

[Roger-luo]

wiki的链接我们都不管了吧. 加上中文wiki也访问不了, 等manual翻译完成以后我们再统一更换一下链接, 到国内能访问到的网址(blog也成)