Skip to content

如何贡献内容

Jump to bottom Edit New page
Wei Wang edited this page Jan 12, 2016 · 12 revisions

欢迎加入objccn.io！

在开始贡献内容之前，您可以需要了解以下几项内容：

Repo的结构和文件命名

objc.io是以话题 (Issue) 来组织内容的，publish 里的内容是当前发布在 objccn.io 站点上的内容；origin 文件夹则以 submodule 的方式包括了所有原文（如果你不懂什么是 submodule ，不要担心，这对你使用不会产生任何影响）。在 publish 中有以 issueX 进行编号的子文件夹，它们对应了 objc.io 站点上的每个话题 (Issue) 。文件夹下的文件遵循统一的命名规范，具体地，每个文件都应当以如下方式进行命名：

issue-{ISSUE_NUM}-{ARTICLE_NUM}-{CONTRIBUTOR}.md

其中

  • ISSUE_NUM 从属的话题序号；
  • ARTICLE_NUM 文章在话题中的序号。所有话题都有一个卷首语 (Editorial)，它的序号为0。之后的文章按照顺序从1开始进行编号；
  • CONTRIBUTOR 贡献者的名字，我们推荐您使用 Github 的用户名，当然您也可以选择其他不带空格或特殊字符的字串，但是在不同的内容和文章中请统一。

文件名例子：issue-1-0-tang3w.md

避免重复劳动

如果网站首页的链接是可用的，或者 publish 页面中已经包含了您想要贡献的内容，则说明这一篇文章已经发布了较完整的版本。如果您认为当前发布版本中存在明显的错误和纰漏，欢迎您通过新建 branch ，然后修改并提交 pull request 的方式来进行修正。

如果想要翻译的文章还没有发布的话，您可以到这个repo的 Issues 页面查看当前翻译的进度和状况。在您决定翻译一篇文章之后，请在对应的issue中进行记录和汇报，这样大家就知道您已经认领了对应文章的并开始进行翻译。认领，记录和汇报进度请直接在现有的 Issue 中通过评论和修改评论的方式来进行，而不要新开 Issue ，这样方便进行汇总和管理。如果您想修改当前的发布版本，请直接向 publish 中提交 pull request ，我们会进行处理。

在翻译时，我们建议您先新建一个自己的 branch ，例如new/issue-10-3-yourname这样的格式，明确表示这个 branch 的内容。然后将 origin 中的对应文章复制到 draft 中对应 Issue 的文件夹下，并按照文件命名规范重新命名文件（添加您的名字）。然后保留英文原文，并在每一段原文下方按照原来的格式进行中文译文的添加。在编辑时，请保留原文格式（不要轻易删除或修改这些符号：[，]，#，`)，除非您有确实的理由）。文章中涉及的图片和链接等内容也请不要任意删改，我们将在最后排版时进行调整。

在翻译完成后，请通过发送 pull request 的方式将您的 branch 的内容提交到 draft 的对应位置，管理人员会在 merge 之前组织校对工作，如果问题都得到解决，我们将进行合并和发布工作。在发布前我们可能会向您询问一段您的简要介绍和邮箱地址，用于文末的译者署名和头像展示。再次提醒您注意，请不要向 master 分支进行直接提交和推送。如果您不是很明白这句话的含义，您可以使用 fork 的方式在您自己的repo上来进行上述操作，具体一点可以参看一下这里的步骤。

objc.io 的文章是具有一定时效性的，而大家也更希望今早阅读到最新的中文资料。但是近期出现了很多“先占坑然后慢慢翻译”的做法，所以希望认领后的文章能在一周以内完成翻译和提交 pull request。如果按时无法完成的话，可能会重新指定更有热情的翻译者。

排版规范和注意事项

origin中的原文已经经过良好排版，我们希望您能够遵守其中的排版规则进行翻译，这会在您进行翻译工作时提高您在定位内容和排查方面的效率，同时也将大大降低我们的工作量，一举两得。下面列举了一些这个项目排版时的规则，请您确认：

  • 文章标题使用 <h1> 标记，#。

  • 章节标题从 <h2> 标记开始使用，按照层次每层增加一级，即##，###等。

  • 代码可以在代码内容每行前使用四个空格开始，或是在代码顶格开始并前后使用三个```符号。注意两种方式不要混用，另外无论使用哪种方式，代码缩进为4个空格。一行太长的代码（包括缩进80个字符以上）请注意在合适的地方进行换行和对齐。Origin 中的原文使用的是前一种方式，但是有时这可能导致您编辑不便，因此后一种方式也是可以接受的。

  • 较为专业术语请保留英文原文，特别是对于普遍习惯使用的短语或者英文内容更容易理解的词。比如，虽然有很多人将 Key Value Observing 翻译为 键值观察，但是应该更偏向于选择 KVO 这样通用的缩略形式。另外，千万不要将诸如 Grand Central Dispatch 翻译为大中枢派发之类的闻所未闻的叫法，请将其简单地写作 GCD 即可。

  • 中文和英文混编时，如果一个英文单词/短语前后是中文字符，请留意随手在英文和中文之间留出一个半角空格，就像上面这条中做的这样

    中文正文及标题中出现的英文及数字应该使用半角方式输入，并且在左右各留一个半角空格。如果这些这些半角英文及数字的左边或者右边紧接着任何的中文全角括号或者其他标点符号的话，则不需要加入半角空格。参见 这个 issue。

  • 代码中的注释我们希望您也能顺手进行翻译。

  • 图片的链接请使用 objccn.io 站点的链接，而不要使用原来的 objc.io 或者相对路径的链接。一般来说，原站链接是这样的形式 http://www.objc.io/images/issue-7/big-o-notation.png ，请您将其替换为 http://img.objccn.io/issue-7/big-o-notation.png 的形式。我们应该已经将所有的图片抓取到了对应格式的 url 上。如果您没有在对应链接上找到该图片，请与我们联系（提 issue 或者邮件）。

  • 原站点某些图片链接含有 @2x 的后缀，这是 Retina 屏幕的对应。objc中国也做了 Retina 屏幕适配，在您遇到这样的链接时，请将 @2x 标记去掉，我们的站点会正确处理这种情况。例如，请将这样的链接 http://www.objc.io/images/issue-1/view-insertion@2x.png 转为 http://img.objccn.io/issue-1/view-insertion.png 这样。

：）就这么多，衷心感谢您的兴趣和阅读，希望您没被吓跑。

Add a custom footer
Add a custom sidebar
Clone this wiki locally