Guidelines for translating Free Code Camp to any language

Guidelines for translating Free Code Camp to any language
0.0 0

#1

Thank you so much for your interest in translating FreeCodeCamp. Reading this document is recommended for participating in a collective effort to bring FreeCodeCamp to more and more people all around the world.

How to Contribute to Translations?

There are various ways in which you can contribute collaboratively to the translations. Every translation effort usually follows the workflow below.

Pro tip: You can contribute to any or all of below phases in the work flow as per your interest.

Guidelines and Resources

General guidelines

  • Try not to be too formal yet not too casual, just to keep things friendly.
  • In order to make contents more understandable for native speakers of your target language (think of those who don’t speak English), translate as much as you can, try to use a word in English only if it is already widely used in the countries where your target language is spoken.

Glossary

It is efficient if all the translators working on the same language create a glossary showing the translation of words in English employed in FreeCodeCamp’s challenges. Sometimes there is more than one way of translating some terms, and regional differences might create confusion (for example, some terms might differ between Spanish from Spain and from Latin America, or between the French language employed in Canada and in France). Be democratic! Choose the most appropriate translation by voting and keep a record of the results. One example of such record can be found here: FreeCodeCamp Glossary (English to Spanish) Use the chat room for discussing the glossary, so no one will miss anything.

If you need some help with the Google Translator Toolkit

You may find help automating the translation process by employing the Google Translator Toolkit, please see: Spanish guide

Creating a test instance of FreeCodeCamp

Seeing the final product as you advance with the translation can help you to stay motivated. That’s why it is a good idea to create a test instance of FreeCodeCamp where you can include the most recent changes of the translation of the language you’re working on and use FreeCodeCamp including those changes. The following test instance was created for the Spanish version of FreeCodeCamp: Getting Started. In order to create a test instance, go through the following steps:

  1. Follow the instructions of Contributing page be sure you can see a running instance in English
  2. Open Supported Languages.js and add the language of your instance.(e.g es: 'Spanish'), restart your instance.
  3. Change the url with a prefix of your language (e.g for Spanish, /en/challenges/ to /es/challenges/), if the page has been translated, you should be able to see it.
  4. Look up the language file, try to search keywords in your repository, you can find all challenges under /seed/challenges/ for example, the Getting Started page is located at freeCodeCamp/seed/challenges/00-getting-started/getting-started.json
  5. Happy translating!
  6. Before you submit PR, please make sure DO NOT include supported-lamguages.js in your commit, ($ git reset -- common/utils/supported-languages.js)
  7. The last but not the least, make sure you follow all rules in Contributor’s Guide.
  8. Thanks for your contribution!

References

If you find it useful, you can translate these instructions to your language and adapt them for your translation team (see for example, original in Spanish.)

This guide is based on this writeup.


freeCodeCamp in spanish?
Internationalization features
#3

Review the work of another translator

When a translator completes or advances a translation they will create a pull request, that must be reviewed by another peer. A Pull Request or PR is a method of submitting proposed changes to the code base.

Translators would post a link to their pull request in the chat room of the language; asking for reviews. If you see a message requesting review of a translation, visit the pull request and find the tab "Files changed" right under the PR’s title. There you will be able to see the changes in the translation in two columns, to the left you will see the original file and to the right the changes proposed.

If you want to suggest an improvement to the translation in one line (a.k.a inline commenting), click on the + (plus sign) that appears next to the line number when you move the cursor over, in the dialog that pops up you can write your suggestion.


#4

Create Translation issues to track the progress.

Before starting translations of challenges, GitHub issues need to be created specific to the language of translation. Translators should create issues with the details of the challenges to be tracked in that particular issue.

**FreeCodeCamp TranslationExpansion’s Issues Section,To start the translation of one of the files in the directory seeds/challenges. See for example: Issue #83

Pro Tip : You can quickly check availableissues by looking for the help wanted label.

If you see issues already open, then you could proceed to working on them, don’t forget to leave comments like “Working on it” to remind the others.

If you can’t see any related issues, or that can’t be reopened, then start by creating issues you would like to work on. Remember to discuss in the Chat room for a confirmation of the challenges that you would like to add to the issue.

Pro Tip : Follow the example shown above, for consistency in the formatting of the issues, like adding checklists for challenges.


#5

Start Translating

When you want to work on any of the translations, we encourage you to leave a comment like "Working on it" on the open/ongoing translation issues. This will notify contributors about your interest in translating that part of the curriculum.

Steps:

  • Check the technical steps in this guide for doing translations.

  • After this you will have up to 15 days to create a Pull Request with the proposed translation or updating an existing one.

  • We invite you to check the directories and files in seeds/challenges for doing translations.

Pro Tip : Remember to discuss your progress in chat rooms. Being active in the chat, reflects that you are working on it!

Technical procedure to create a translated file

  1. Install Git on your computer and create an account on GitHub if you don’t already have one.

  2. From your GitHub account fork FreeCodeCamp’s repository (https://github.com/FreeCodeCamp/FreeCodeCamp). That’s it! Now, you have a fork of the original repo under your account.

  1. Launch the terminal and clone a local copy of your fork to your computer (replacing the word USERNAME with your github account’s username):
git clone --depth=1 https://github.com/USERNAME/FreeCodeCamp.git
cd FreeCodeCamp
  1. On GitHub, go to the Issues Section of the FreeCodeCamp repository and look for the open translation issues. Leave a comment similar to "Working on it" if no one else appears to be already working on it (or has been inactive for over 2 weeks).

  1. In your forked repository, create a branch with a name such as "translate/Lg-translation-XXX-YYY" where Lg is the abbreviated name of the language you’re working on, and XXX-YYY is the name of the file you’re going to modify.
git checkout -b translate/Es-translation-basic-javascript

In the example above Es is the language code for Español (Spanish) and basic-javascript is the name of the JSON file that is to be translated. Refer the list of Two letter codes for your language, for clarification.

  1. Find the JSON file in the seeds/challenges directory for the challenge you want to translate.

You can verify the JSON syntax by copying and pasting the contents of the file into http://jsonlint.com.

  1. When you’re done, reset supported-languages.js first, commit your changes with a brief description in English (regardless of the language). Afterwards, you can push the changes to your fork:
git reset -- common/utils/supported-languages.js
git commit -m "Challenges of Basic Javascript translated into Spanish" seed/challenges/basic-javascript.json
git push origin add/Es-translation-basic-javascript

If you think that you can’t continue for a while with a translation, you can leave a comment on the same issue, indicating that another person should continue. You can push your incomplete changes so the next person won’t duplicate your hard work.


#6

Create Pull requests to add the Translations to code base.

As mentioned earlier, a Pull Request or PR is a method of submitting proposed changes to the code base.

Afterwards, from the web page of your fork in github.com, make a pull request to the branch called staging in the main repository (see the help). Add “Closes #yyyy” to the description area in the Pull request where yyyy is the issue number of the original issue that was created for the challenge translation. Doing this will automatically close the open issue when the PR is merged.


#7