团队约定草稿

[songww]

这真的是一份草稿，有很多错误的草稿。

从我知道transifex上有人在翻译中文文档到现在正好半年了，从当时四五十个翻译人员到现在一百三十八个，是Python翻译团队里人数最多的一个。
进度虽然不是最快的，但是现在翻译过的数量也超过8%了。

可是质量却是惨不忍睹。真的惨不忍睹。

最近在 @zhsj @zhangyangyu 两位大佬的带领下拉了一个微信群，希望能把大家的力量组织起来，先把中文文档上线。

为了大家翻译的文档更有意义，质量更好，我们想出一份团队约定，指导大家如何更好的完成翻译。
本来这个文档应该由牵头人也是tx的协调员 @zhsj 来起草的，奈何他实在太忙了。

所以我起草了这份草稿，真的是草稿，有很多错误的草稿。目的是抛砖引玉，吸引大家更多好的建议。
希望大家都能参与进来提出自己的建议，讨论出每个人都认同的一个约定。

希望大家畅所欲言，任何意见建议都可以提过来。
如果有谁写了一份更好更完善的，我也可以立马把这个PR关掉。

希望这是一个大家都认同的团队，都愿为一份更好的文档而加油的团体。

最后，之所以使用PR，是因为大家可以针对每一条进行评论，回复，交流。

[songww]

``:ref:`installation guide``` 这个是不是应该翻译？好像翻译了也是可以正确跳转的？

[silkriver]

我发现有些是像 :term:arguments ( 1 ] 这样的形式，arguments可以翻译，起跳转作用的是那个( 1 ]不要去动

[songww]

这个可以单列一条，我加在后面。

[silkriver]

因为官方文档有术语表，Transifex也有词汇表，我觉得约定里面不必再放了

[songww]

@silkriver 文档的术语表与tx的或约定里的，目的是不一样的。
文档里的术语是给所有人看的，而tx的或我们自己的是给翻译的同学看的，可以包含很多很多文档里没有列出来的。
tx的术语不支持多个含义，而且维护起来很费劲。很多词在不同的语境下含义是差得很多的，比如今天讨论的 Token 。
另外有的词在不同语境下用不同的词可以用更好的表现力。
维护我们自己的术语表就可以为这些不同语境添加不同例子，指导大家完成更好的翻译。

我写的只是很初级的，甚至故意留了很多错误，就是想让大家讨论起来，争相发表意见。

[silkriver]

argument是参数、实参，parameter是形参，Python文档里是区分开的

[hzhu212]

是否考虑增加一条翻译建议？

英译中的时候，不要刻意追求标点符号和断句的严格对应，毕竟英文和中文的阅读习惯是不同的。

英文的句子往往很长，很多句子横跨三、四行而不加标点，这是因为英文习惯堆砌定语、状语、从句等。但是中文不一样，中文一旦超过一行而不断句，读起来就会很吃力。

因此我觉得翻译英文长句的时候，最好要断句。

我今天遇到很多这样的句子。例如：

The :mod:reprlib module provides a version of :func:repr customized for abbreviated displays of large or deeply nested containers::

现有的翻译是：

:mod:reprlib 模块提供了一个用于大型或深层嵌套容器的缩写显示的 :func:repr 版本::

我觉得远不如翻译成：

:mod:reprlib 模块提供了一个定制化版本的 :func:repr 函数，用于缩略显示大型或深层嵌套的容器对象::

后者虽然看起来更长、更罗嗦，但读起来却更容易。

[songww]

argument是参数、实参，parameter是形参，Python文档里是区分开的
👍

@hzhu212 👍

[bmxbmx3]

这真的是一份草稿，有很多错误的草稿。

从我知道transifex上有人在翻译中文文档到现在正好半年了，从当时四五十个翻译人员到现在一百三十八个，是Python翻译团队里人数最多的一个。
进度虽然不是最快的，但是现在翻译过的数量也超过8%了。

可是质量却是惨不忍睹。真的惨不忍睹。

最近在 @zhsj @zhangyangyu 两位大佬的带领下拉了一个微信群，希望能把大家的力量组织起来，先把中文文档上线。

为了大家翻译的文档更有意义，质量更好，我们想出一份团队约定，指导大家如何更好的完成翻译。
本来这个文档应该由牵头人也是tx的协调员 @zhsj 来起草的，奈何他实在太忙了。

所以我起草了这份草稿，真的是草稿，有很多错误的草稿。目的是抛砖引玉，吸引大家更多好的建议。
希望大家都能参与进来提出自己的建议，讨论出每个人都认同的一个约定。

希望大家畅所欲言，任何意见建议都可以提过来。
如果有谁写了一份更好更完善的，我也可以立马把这个PR关掉。

希望这是一个大家都认同的团队，都愿为一份更好的文档而加油的团体。

最后，之所以使用PR，是因为大家可以针对每一条进行评论，回复，交流。

请问微信群怎么加？

[silkriver]

我清除了有问题的地方，现在提交不会出错了 https://github.com/python/python-docs-zh-cn/commits/3.7
容易出错的地方我觉得应该强调一下，RST前后要有分隔符这样的问题应该列在约定的最前面免得检查报错。此外约定还需要增加以下条目：

1. 冒号除非后面确定跟的是汉字否则还是用半角，例如很多词条末尾的冒号实际上系统会自动在后面再加一个空格，用全角冒号会太宽
2. 括号除非前后确定都是汉字否则还是用半角，全角括号不被认为是分隔符，与RST标记间需要加空格也会太宽

[zhangkaizhao]

支持支持！
发现一处错别字：“跌代”应该为“迭代”，“跌代器”应该为“迭代器”。

[songww]

我清除了有问题的地方，现在提交不会出错了 https://github.com/python/python-docs-zh-cn/commits/3.7
容易出错的地方我觉得应该强调一下，RST前后要有分隔符这样的问题应该列在约定的最前面免得检查报错。此外约定还需要增加以下条目：

1. 冒号除非后面确定跟的是汉字否则还是用半角，例如很多词条末尾的冒号实际上系统会自动在后面再加一个空格，用全角冒号会太宽

2. 括号除非前后确定都是汉字否则还是用半角，全角括号不被认为是分隔符，与RST标记间需要加空格也会太宽

关于标点符号后面跟空格显得空白太长的问题，我有写的。

:: 是RST语法，表示 字面代码块

在段落的后面使用标记 :: 引出. 代码块必须缩进(同段落，需要与周围文本以空行分隔):

如果作为独立段落存在,则整段都不会出现在文档里.
如果前面有空白，则标记被移除.
如果前面是非空白，则标记被一个冒号取代.

我的建议是使用 例子： :: 这样的方式。中文冒号与两个英文冒号中间增加空格，这样不会影响rst语义，也不会有多余的冒号被渲染出来，更可以解决中英文符号混杂的问题。

有其他方式且更好解决的问题，那其就不应该成为 中文夹杂英文符号 的理由。

[silkriver]

或者干脆就规定一律用西文半角冒号和括号，编程文档的特点必定是中文夹杂英文符号，同种符号保持统一最好看 (其实好看也是第二位的问题，编辑时方便自然显示时没有异常最重要)

另外可以提示大家及时对照翻好的页面看有无显示错误
如果编辑的文档是 https://www.transifex.com/python-doc/python-newest/translate/#zh_CN/reference--datamodel
则对应的页面就是 https://docs.python.org/zh-cn/3/reference/datamodel.html

[songww]

支持支持！
发现一处错别字：“跌代”应该为“迭代”，“跌代器”应该为“迭代器”。

Fixed

[songww]

或者干脆就规定一律用西文半角冒号和括号，编程文档的特点必定是中文夹杂英文符号，同种符号保持统一最好看 (其实好看也是第二位的问题，编辑时方便自然显示时没有异常最重要)

这个看大家的意见。仅反对中文语句中中英文标点混用。（即一会儿用中文的，一会儿用英文的。

[Dumeng]

推荐以前翻译时的规范，引号一律翻译为「」，区别中英文

[silkriver]

推荐以前翻译时的规范，引号一律翻译为「」，区别中英文

大陆地区习惯是只在竖排时用这个了，输入法都没有相应的键，这样规定恐怕很难推行

[songww]

推荐以前翻译时的规范，引号一律翻译为「」，区别中英文

大陆标准里这个是竖排时使用的。「」『』，且如 @silkriver 所说，很多人可能都找不到这两对符号在哪个键上。
（我是喜欢这两对符号的，比全角引号好看多了

当然最后还是看大家更愿意用哪个，我（很多条目都比较纠结）只是把想到的（从候选里选了最保守的）列到了这里。

[chen-chao]

关于标点，我觉得其实用英文标点更好，避免很多麻烦。不过目前应该都是用中文标点，除非决定大改，不然还是沿用下来吧。

另外问一下，现在遇到段落最后的冒号和双冒号，还是应该用英文标点吧？

[songww]

关于标点，我觉得其实用英文标点更好，避免很多麻烦。不过目前应该都是用中文标点，除非决定大改，不然还是沿用下来吧。

另外问一下，现在遇到段落最后的冒号和双冒号，还是应该用英文标点吧？

单个冒号是要翻译的，双冒号是rst的语法标记，不应翻译。