How to submit translation contributions to Microsoft Docs and the localization community

Docs (docs.microsoft.com), a new version of Microsoft's documentation site, has re-planned the document structure of each technology stack to look better than MSDN. Although Docs is available in a variety of languages, most are machine translation, and some Chinese documents are largely unreadable. So Microsoft encourages community participants to submit localized content. For Microsoft MVP, participating in the localization of Docs is also an important way to contribute. In addition to the localization of Docs, Microsoft also has a localization community that can localize Microsoft's multiple software programs: Microsoft Localization Community. Next, let's introduce how to contribute to these two projects. If you are already familiar with GIT operations, you can skip this article.

Leaderboards and points rules

Microsoft released a leaderboard to see the scores of global contributors: Microsoft Cloud + AI International Community leaderboard (https://microsoftl10n.github.io/)

The scoring rule is this:

• For Docs, each recommendation is 15 points, and if Microsoft accepts the recommendation, it can get 60 points. That is to say, a maximum of 75 points is recommended.

  1. Docs Localization score = number of recommendations * 15 + accepted Recommendations * 60

  2. One suggestion = 15 points

  3. One approved recommendation = 60 points

• For a software program, if you review and modify a sentence that contains 10 words, you get 20 points. If the translation is approved by Microsoft, you can get 80 points. This translates to a maximum of 100 points for a sentence of 10 words. At the same time, if you review other people's translation and vote, you can get 2 points.

  1. Software localization score = suggested number of words * 2 + votes * 2 + accept translated words * 8

  2. A suggested Word = 2 points

  3. An approved Word = 8 points

  4. Translation of votes to other persons = 2 points per vote

Of course, I would like to emphasize that we do not contribute to the score, the submission of PR is a very fulfilling thing, your contribution can help others, but also a raise for themselves, this is the meaning of contribution.

Submit PR to Docs

Here's a detailed description of how to submit a PR () to Docs Pull Request .

Modify directly on the page

The first is to modify a single word, sentence, or article directly on the page. Take this page for example: https://docs.microsoft.com/zh-cn/dotnet/standard/design-guidelines/choosing-between-class-and-struct

"One of the basic design decisions of the face of each frame designer ..." What a mess. The quality of Bing translation needs to be improved.

First click on the button in the upper right corner of the page 登陆 , you need to use the GitHub account here, without first registering one. You can then see a few links above the page:

You can click the 反馈 button to submit your feedback, which is equivalent to posting a comment that appears below the page. If you want to edit the translation, click on the 编辑 button, this will directly link to the GitHub address on the page:

To edit it, click on the Edit button for that pencil:

Then you can edit it directly and note the instructions at the top of the page:

Using this method will automatically create a branch in your warehouse. Click on the Propose file change button below:

This will automatically generate a page, compare the changes made, click the Green Create pull requet button to create a PR:

Create PR:

As you can see, this approach is actually creating a patch-1 branch named:

After the PR is approved and merged, you will be prompted to delete the branch because the branch is useless. Follow the prompts to do so.

ForkProject to your own warehouse

The way you modify it directly on the page is simple, but can only be done online, and you may lose data if you encounter a broken network or a system crash. In addition, only to change a few words to submit a PR, appear relatively fragmented. It is recommended to fork the project to its own warehouse, after the local modification, and then submit the PR. Local editors use vs code or other editors, and no data is lost, and VS code automatically saves changes.

ForkEquivalent to a copy of a warehouse. Fork the source project to your own warehouse to allow you to modify the code without affecting the source project. And you can also submit your changes to the source project. The general process is this:

• Fork the source project to its own warehouse

• Modify

• Submit to Source projectPull Request

If the original project author agrees with your changes, it will be merged into the source project.

Fork Project

First, open the main page of the official project and fork it to your warehouse:

This will generate a new project in your account and show the fork from the source project:

Use VS Code to Clone the project locally. If you don't have a VS Code, you can have one, a front-end artifact, and an integrated Git, which markdown is great for writing. Docs's documents are all markdown formatted, so VS Code is a good fit to do this.

Click Clone or download the button, and then click the button next to the path to copy the project path:

Because the VS code already integrates git, there are two different ways to use Git in VS code:

• Press F1 to bring up the command input box and enter Git to see the various supported Git commands:

• Press CTRL + ', or you can enter the Git command directly in the Terminal window:

Choose the way you like. If you use the first method, select the Git: Clone command, and then enter the project path, carriage return, a dialog box will pop up that selects the folder location, and then select OK to Clone the item to the folder.

If you use the second method, first locate the folder where you want to store the warehouse, and then enter:

git clone https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git

Setting up synchronization with source items

Clone project, you also need to set up a local project to associate with the source project (upstream) so that it can be synchronized.

Using terminal to navigate to the directory where the project is located, enter the following command:

git remote -v

The output is as follows:

c:\Source\dotnet.docs.zh-cn>git remote -vorigin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (fetch)origin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (push)

Next, enter the following command to set the local directory upstream :

git remote add upstream https://github.com/dotnet/docs.zh-cn.git

And then enter the previous command to see that the display has been set successfully:

c:\Source\dotnet.docs.zh-cn>git remote add upstream https://github.com/dotnet/docs.zh-cn.gitc:\Source\dotnet.docs.zh-cn>git remote -vorigin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (fetch)origin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (push)upstream        https://github.com/dotnet/docs.zh-cn.git (fetch)upstream        https://github.com/dotnet/docs.zh-cn.git (push)

Create a branch

Go back to your project page (not the Official source project page), click the drop- Branch down list box and enter a new branch name:

Note that when you choose, you should be aware of which branch is the basis, the default is the live branch, and you can choose to create your own branch based on the other branches.

Once you have created a branch, you can switch to that branch locally to modify it. I'm still more inclined to use the VS Code integrated command, which is not easy to make mistakes.

Use VS Code to open the project directory just Clone, press the F1 Bring up command input box, enter Git , you can see the supported Git commands:

Select Git: Checkout to... to select the branch you just created:

This allows the local branch to switch to the branch you just created, and in the lower left corner of the VS Code you can see what the current branch is:

Click on the lower left corner this place can also easily switch branches.

If you use the command line, you can enter the following command:

git checkout xy-test

The output is as follows:

‘xy-test‘Your branch is up to date with ‘origin/xy-test‘.

Now you can make a bold change.

Modify

This time we will revise another document. Open member.md , which is the source file for the Https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/member page.

Translation is done against the original English text. To see markdown the effect, you can install a plug-in. Click the Fifth button in the VS Code sidebar to open the Plugins manager, enter markdown the search, and install the first two:

These two plugins can effectively improve the efficiency of your writing markdown document, and you can also preview the effect on the right. Specific features to see the description of the plugin.

Save when you are finished modifying. Click on the third icon in the VS Code sidebar to see that there has been a change, enter comment, and click on the checkmark to submit.

Such modifications are only submitted to the local repository and will need to be Push to the remote repository. Click the three-point button on the right, and select Push :

If you choose Push to... , you can also choose to Push directly to the upstream branch, that is, the official project, but this is not authorized, so can only be submitted to their own projects, and then to the official project PR.

Back to your warehouse page, you can see that GitHub has detected an update that has been submitted, and then you can click on the right button to create Pull Request :

You can also click the tab bar Pull Request and there will be a New pull request button. This will cause a page to compare the modified file to the source file:

Be sure to note the above branch selection, which is submitted from our own branch to the source project branch, not the wrong choice. It is recommended to enter detailed comment to facilitate official inspection.

The last Crete Pull Request button clicked, the PR was created successfully:

After the Microsoft staff review, it can be merged into the main project branch. Microsoft may make some changes during the period.

Delete local Branch

Often locally created branches are modifications made to a issue, or fix a bug, or add a new feature. When modified and successfully merged, the branch is useless. You can click the Delete button after the branch to delete:

Note that once deleted, it cannot be restored, so be sure to confirm that the contents of the branch have been successfully merged and then deleted.

Synchronizing with a source project

For a long time, our local project may have been significantly behind the update of the source project. Therefore, if the local branch does not make a significant disruptive change, it is recommended that you maintain synchronization with the source project.

First click on the column of your own warehouse item Pull Request and click the New pull request button.

Notice at this point that the default is to commit changes to your project to the source project, and we will, in turn, commit the changes to the source project to our own project.

So select your own warehouse by selecting the drop-down list box on the left:

So the two sides are their own projects, and then click on the compare across forks link:

Select the source project from the drop-down list box on the right:

You can see that the source project has been updated a lot, click the Create pull request button to create a PR.

Because it is your own project, you can merge the PR directly:

After merging, your project is updated to the progress of the source project. Then you pull the updated content locally.

In VS Code, press F1 to open the Command Line window and enter git pull :

Or click the third button in the sidebar, the top right corner of the three-point button, select Pull :

So the local project is also up-to-date.

Now everyone should have a general understanding of how to contribute to Docs translation. I don't have all the Git commands, and using VS Code makes it easy to do something with the command line instead.

Submitting contributions to an application

This is quite simple, add this URL to the Favorites folder:

https://envelope-community.azurewebsites.net/

First select the language and then click the button on the right to vote for the currently existing translation, or enter your own translation in the input box below:

This page supports mobile browsing, so you can also brush a few translations when waiting for the bus.

Conclusion

Docs is a very good learning material, the quality of the article is also relatively high. Being involved in translating Docs is also a way to improve English proficiency. Try to see a little every day, long time will find English reading ability will be greatly improved, by the way for the community to make some contribution, why not? Hope to have more students to join the team of contributors to help others while also improve themselves.

How to submit translation contributions to Microsoft Docs and the localization community