给 MDN 文档本地化参与新人的一些入门指导和经验分享

MDN 文档介绍

MDN 文档，全称是 Mozilla Developer Docs（Mozilla 开发者文档，顺带一提火狐浏览器就是 Mozilla 家的），基本涵盖了前端开发的所有知识，可以说是前端开发学习必不可少的参考资料。才怪，我就是看菜鸟教程入门的前端。

MDN 文档的现状

MDN 文档现在托管在 Github 上（所以说文档的本质是代码 (￣y▽,￣)╭ ），每一篇文章都是用 Markdown 写的（关于 Markdown 的入门介绍可以参看我的这篇文章）。所有人都可以通过 Git 这个工具来参与贡献。（不熟悉 Git？其实不用 Git 也可以贡献哦，后面介绍）MDN 文档在 Github 上主要分为两个部分，一个是 Content 仓库，存储英文文档，还有一个是 translated-content 仓库，与 Content 仓库的结构基本相同，不过是存储翻译（更精确的术语，本地化）后的文档。Translated-content 仓库就是本文关注的重点啦。

目前 MDN 文档的简体中文本地化还是很活跃的，差不多每天都有人提交新的翻译。但是还是很缺人手的。（以前我写代码比较英文文档和中文文档，发现有大约 8000 多篇文档没有被本地化 w(ﾟДﾟ)w，而且很多老文章质量有待提升）如果你能参与其中的话，会是对 MDN 本地化工作的极大帮助（I WANT YOU.jpg）。

MDN_本地化招聘海报

如何给自己找任务

入门级：提升排版

首先，入门级别的任务就是提升文档的排版，早期的 MDN（迁移到 Github 之前的）的一些本地化的文档的排版工作做的很不好，有很大的提升空间。关于文档排版方面要注意的点，这篇文章里有详细的介绍，我挑几个重要的讲：

  1. 标点符号：除了代码里的符号及一些特殊情况之外，其他地方都用中文（全角符号）。
  2. 中文和英文，中文和数字之间要有一个空格：传说盘古开天辟地，在天与地之间辟出了一片空白，故这个空格又名盘古之白（有一个专门搞排版的工具就叫盘古）。
  3. 不要将“you”翻译为“您”，MDN 是程序员写给程序员看的文档 程序员有，程序员治，程序员享（By the programmers, for the programmers），大家彼此平等也就不需要用敬辞了。
  4. 英文单词不要用复数形式：比如说 APIs 翻译到中文之间翻译成 API 就行了。你总不能翻译成“API 们”吧。

这种排版问题真的随便翻一翻就能找到很多：

20230917214438

比如这里就出现了汉字和字母之间没有空格的问题，这个时候肯定有同学就跃跃欲试地想要提交修改了，那么该怎么样提交呢？这里就教大家最简单的方法：

  1. 解决网络问题：这个对于大家应该都不难吧
  2. 注册 Github 账号：注册账号的链接在这里 ┏ (゜ω゜)=☞ https://github.com/signup，Github 账号实际上也就是 outlook 邮箱的账号。顺带一提直到我写这篇文章的时间（2023 年 9 月），注册 outlook 邮箱账号是不需要电话号码的，也不需要你提供一个验证邮箱 循环套娃这是，只需要通过机器人验证就行了。建议大家多攒两个 outlook 邮箱账号。

20230917215204
万恶之源

注册完账号之后，再次回到要提交修改的那个 MDN 文章的页面上，来到文章底部，你会发现有个“Edit the page on GitHub”的链接，点击一下。

20230917215920

之后，来到这个文档对应地 Github 页面（没错，MDN 页面的来源就是这里），开始对对应内容进行修改（没有修改的话，那个“Commit changes”按钮是灰的）。

修改完后，点击“Commit Changes”按钮（Commit Changes 就是提交修改的意思）。

20230917220738

之后，填一下 Commit message（关于提交的信息），这里最好用英文，为啥中文本地化贡献者都是中文用的很熟练的人，却要用英文咧？这是因为 MDN 是一个全球性的开源社区，里面的很多贡献者未必会中文，如果用英语的话，可以让其他语言的人也能参与进去。

20230917221050

之后，点“Propose changes”按钮（还是提交修改的意思）。

之后来到 Comparing Changes 页面（比较修改页面），这个页面信息比较多，不要慌，这里其实很简单，就是以直观的方式显示你所作的修改（红色为原文，绿色为修改后的文章）。

20230917221735

之后点击那个“Create pull request”按钮（pull request，简称 PR，就是拉取请求的意思，可以理解为请求拥有仓库（这里是 MDN 文档）管理权限的管理员接受你对代码（这里是文档）的修改）。

之后，来到“Open a pull request”页面。（创建一个拉取请求）

20230917222626

最后一步了！激不激动

这里简单地填一下信息就行了。依然是最好用英文填。

20230917223203

注意这里我在标题那里标了一个“zh-CN”前缀，这是干啥用的捏？记得我前面说的吗？MDN 是个全球社群，你看这个“Pull Request”列表里就有“ko”（Korea，韩文）、“zh”（中文）、“ja”（日语）和“fr”（法语），标一个语言前缀可以方便辨认具体是来自哪个语言的 Pull Request。其实你不标，MDN 的 bot 也会自动给你打上语言标签的啦（在每个 PR 标题的后面）。

20230917223407
万国来朝

20230917223203

回到正题，这里“same as title”就是同标题的意思，下面哪个“ditto”是啥意思呢？“ditto”来自于托斯卡纳方言，可以追溯道意大利语的“detto”，再往上可以追溯到拉丁文的“said”，就是“一样（在这里是和上文一样）”的意思，这个也是我从 MDN 的另一个本地化贡献者 @JasonLamv-t 大佬那里学到的😁。

之后，点击“create pull request”按钮。

20230917224955

到此任务就完成了，接下来等 MDN 的管理员来处理你的 Pull Request 并拉取就可以啦。才怪，管理员给建议之后，你要按建议改才行 等你的修改被接受（专业术语，merge）之后，过一段时间，你就可以在那篇 MDN 文档那里看到你的修改了，当然 Github 的那篇文章的 commit history（提交历史）上也永远地留下了你的足迹！

备注：提交 PR 之后，发现有漏网之鱼是很正常的事情，那么该怎么修改呢，答案是点那三个点之后再点 Edit file 就行了，之后按照前面的提到的 PR 流程自然走就行了。

20230917233310

进阶级：翻译整篇文章

那么接下来，如果你还有余力的话，就可以参与整篇文章的本地化了。

那么怎么需要翻译的文章呢？这里提供两个技巧：

  1. MDN 文档语言调成简体中文，之后看到目录里后头标有（en-US）的，都是待本地化的文章。

20230926214700

  1. MDN 文档语言调成英文，之后点击打开语言列表，如果里面没有“简体中文”的选项，那么就说明这篇文章待本地化。

20230926213957

如果是涉及到创建整篇文档的话，那么直接在 Github 页面里修改就不那么适当了。这个时候我们就要用到 Git 了（回想当初刚参与贡献时也是在 Git 上踩了不少坑啊 （；´д｀）ゞ 希望我的这点经验能帮助新人少踩点坑吧）。

Git 简单介绍

简单介绍一下 Git 的来历。Git 是 Linux 内核的作者 Linus Torvalds 开发的。他为啥要开发 Git 呢？要知道 Linux 内核是一个几千万行代码的庞大项目，而且 Linux 内核源码的贡献者来自世界各地，组织结构很松散，管理起来可不是个容易事。为了方便 Linux 内核源码的管理，Torvalds 创建了 Git。连 Linux 内核源码都能轻松管理，MDN 文档源码更是不在话下了。

Git 的简要流程：

预准备工作：

  1. 首先，我们要安装 Git 还有 VS code。
  2. 进入项目的 Github 主页 https://github.com/mdn/translated-content 。
  3. 点这个“Fork 按钮”。这个 Fork 是啥呢？简单来说 Fork 操作就是创建一个自己的仓库再把要参与贡献的项目的仓库（这里是 MDN 仓库）复制到自己的仓库（不是复制代码哦，而是把所有的 commit history（提交历史，指提交的对仓库内容的修改）都复制过去）。为啥要有这样的操作呢？因为你是没有原仓库的修改权限的，要做什么修改只能经过管理员许可才行。而把仓库 Fork 过来之后，你就拥有了一个拥有修改权限的并且和要贡献的仓库代码一模一样的自己的仓库，这样你就可以随意修改而不需要经过他人许可了。

20230926220719

  1. 打开 Git Bash，输入以下指令生成你的 ssh 密钥：ssh-keygen -t rsa -C "youremail@example.com"
  2. 输入指令 cat ~/.ssh/id_rsa.pub，得到公钥
  3. 打开这个网址 https://github.com/settings/keys，之后点 New SSH key，然后标题随便输一个，再把公钥粘贴进去就行了。
  4. 打开 Git Bash，设置自己的名字和邮箱
git config --global user.name <your-name>
git config --global user.email <your-email>

由于本教程是 MDN 本地化贡献教程，没办法把 Git 介绍的很详细。这里简要介绍一下 Git 的工作流程：

  1. 把仓库克隆到本地（也就是自己的电脑） Git clone <repo-url>，这里的指令应该是 https://github.com/<你的 Github 用户名>/translated-content
  2. 用 VS code 打开本地仓库
  3. 设置 upstream（上游）仓库：git remote add upstream https://github.com/mdn/translated-content.git
  4. 来到主分支：git checkout main
  5. 拉取最新的 commit：git pull upstream main
  6. 创建一个新的分支（git checkout -b <新分支名称> main 为例），这里创建新分支的目的是不要污染自己的主分支（注意，主分支的作用仅应该是与上游仓库同步，其应永远保持仅作为其他分支的基础，而不应该直接在主分支进行修改）。命令后面那个 main 的意思是新分支以 main 分支的 commit 历史为基础。
  7. 在项目文件夹里做自己的工作（在这里即翻译文档）（在这里才开始正式工作，Git 真的挺难入门的，但是入门之后就会越用越爽，这一点和 Vim 类似，这也比较符合我的工具审美）。
  8. 工作完成后，依次输入 git add .、git commit -m <你的提交信息> 还有 git push origin <新分支名称>
  9. 打开 MDN translated-content 仓库 Github 页面，你会看到一个黄色的 pull request 提示，点击之后步骤和之前的 pull request 差不多。
  10. 想再做出新的 commit 的话，回到第三步并不断循环。

总结

本篇文章先是介绍了如何在 Github 网页上贡献 MDN 翻译，之后介绍了如何用 Git 来贡献翻译。如果这篇文章能对你有帮助，那我真是荣幸之至。如何有什么问题的话，欢迎通过 email 联系我。我的邮箱地址是 yujiehan2002@outlook.com。