Gatsby’s documentation includes a very thorough contributing guide for translation which includes processes as well as helpful advice to potential maintainers. Some of the advice is specific to translation while other advice is more general good documentation habits that becomes more relevant in a multilingual environment.
I’ve done my best to just summarize the process here along with the tips related to translation. For the full list of considerations please consult the official Gatsby documentation.
The general process
Each translation has its own repository in the organization on GitHub, with designated codeowners to review and approve changes. Each repo will include all pages needing translations (with some prioritized over others), and a bot to notify of changes in the main repo to keep everything up-to-date.
-
Maintainers: Each translation repo will have at least two maintainers and codeowners that are responsible for the upkeep of the repo.
-
Language-specific channels: Each translation group may want to have a space for maintainers and community members to ask questions and coordinate the project.
Creating a translation
Before requesting a new translation read the maintainer responsibilities to affirm that you accept the responsibilities of being a translation maintainer. Check the list of open translation requests and if you don’t see the language listed create a new translation request issue.
Finding codeowners
For a new translation, open an issue with information about your intended language. If you don’t already have co-contributors to act as fellow code owners check out other translation request issues people have made and offer to join.
Criteria for translation approval
A translation request will be chosen for approval based on the following criteria:
- Are there at least two maintainers listed?
- Do at least one of the maintainers have previous open-source experience and experience working with GitHub and git?
- Are the maintainers fluent speakers? Maintainers do not need to have experience translating, but must be fluent enough in the language to be able to translate technical writing.
Once the translation request is approved, a member of the core team will run an automated script to create your repository and set everything up.
Use English as the source
The website is written first in English and should be considered the source material for all translations (as opposed to starting from another translation).
- When a repository is created, it will provide a copy of the docs to be translated which you can then update through pull requests against them in the relevant language.
- Changes to the meaning of a text or code example should be done in the main English repo, and then translated afterwards to keep the content aligned across languages.
Translation Maintainer Guide
Maintainer responsibilities
- Keep issues up-to-date as people volunteer to translate pages.
- Review pull requests made by contributors promptly.
- Review auto-generated pull requests generated in order to make sure translations remain up-to-date with the source repo.
- Act as point of contact for your language and answer questions from both contributors to your language and the core team.
- Set up a process in order to get your translation published.
As a maintainer, you are welcome to add a contributing doc written in your language to assist with the process.
Tips
Set up a style guide and glossary
- Your language repo comes with a template style guide that you can use to put in style rules specific to your language.
- Refer to the translation style guide for more information.
Prioritize pages
- The repo creation script will create a progress issue listing the list of core pages to translate. Once these core pages are done, make to update the issue or create a new one in order to schedule work for the rest of the docs.
- Reference guide overview pages are also worth translating to establish a fully translated path to a frequently visited reference guide, though overview pages are listed at a lower priority.
Spread the word!
- If you’re finding it hard to find people to help translate, spread the word about your translation effort!
- Ask people in local meetups if they would be interested in contributing.
Translation Style Guide
- Each translation group should decide on conventions and stick with them for consistency, documenting those decisions in the repo’s style guide file to set contributors up for success.
- Use the English style guide as a reference to determine the equivalent rules in your language.
- Translated docs and learning materials should maintain these values with high-quality spelling and grammar, accurate information, similar structure and purpose.
Glossary
- The style guide has a glossary section that you can use to fill in common translations.
- Look at the English Glossary for a list of terms that are useful to have translations for.
Universal style guide
Keep the meaning of the source
- Keep the meaning of the original English source even if it is confusing or has a typo.
- If you find an error that can be fixed, create an issue or pull request to the original repo so that all translations can benefit from the change.
Text in code blocks
- Leave text in code blocks untranslated except for comments.
- You may optionally translate text in strings, but be careful not to translate strings that refer to code!
