Here’s an abridged version of Gatsby’s contributing guide for translation.
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.
Creating a new translation
See Starting a new language to start up a new translation repository.
Contributing translations
See the translation contributor guide for information on how to contribute translations in your language.
Maintainers
Each translation repo will have at least two maintainers and codeowners that are responsible for the upkeep of the repo. See the Translation Maintainer Guide for information on the responsibilities of translation maintainers.
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
Read the maintainer guide
Before requesting a new translation, make sure to read the maintainer responsibilities to affirm that you accept the responsibilities of being a translation maintainer.
Check other issues
Before creating a new issue, make sure to check the list of open translation requests. If one already exists for your language, ask to be added to the list of maintainers there.
Create a translation request issue
If you don’t see the language among the issues listed, feel free to create a new translation request issue for it and follow the instructions.
Finding codeowners
For a new translation, open an issue with information about your intended language. If you already have co-contributors to act as fellow code owners and provide checks and balances for PR reviews and quality assurance, that would be very helpful! Otherwise, you can 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.
After approval
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.
Contributing to a Translation
Once a language repository is created and someone on the core team has assigned codeowners, contributions can begin. It is up to the discretion of the contributor how exactly they want to work, but it’s recommended to limit the scope of PRs to 1 doc at a time to aid with code reviewing.
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.
Common types of merge issues
Typos fixes
Sometimes there is a typo or grammatical error in the English source that gets fixed in an update. Since these typos most likely don’t exist in the translated version, you can most likely use the translated version as-is.
Content changes
Sometimes, the content of the source page is actually updated and needs a translation. Make sure to read the change carefully and change the translation to match its meaning.
Conflicts in untranslated files
Sometimes, you may find conflicts in files that haven’t been translated yet. This is usually because of a previous improper merge (for example, using the “Squash and merge” option).
Creating a separate pull request
If a page has significant changes, it may be worth splitting it into its own pull request.
Translation Maintainer Guide
This page lists the responsibilities of translation maintainers and provides tips on how to better manage your repository.
Maintainer responsibilities
Your responsibilities are as follows:
- 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.
Set up a review process
As codeowners, you have the freedom and responsibility to decide what your review process will be like. You can decide how many reviewers you’d like. If your team is small, one reviewer may be enough. But if you have lots of contributors and enough codeowners, you may want to require two reviewers for additional quality.
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.
Ask for help
Don’t be afraid to ask for help!
Don’t let translations stall
Check in periodically with contributors to make sure translations are being done promptly. If it’s been a while since a page was assigned without any progress, check in with the contributor and ask for a status update. If the contributor is unresponsive, you may need to free up the page for someone else to work on.
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.
Template responses for closing PRs
Sometimes a PR has a valid reason to not be merged as-is. Templates can help speed up the process of responding to someone while encouraging future contributions.
PRs with quality issues
If a PR includes content that is of poor quality (such as from Google Translate or missing important nuance) or doesn’t meet the requirements, it would help to include a drafted reply to encourage contributors to continue with the project.
PRs with changes more fitting for the main Gatsby repo
Because the main Gatsby repo is the source of content, more substantive changes should be closed and redirected there.
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. For any questions about guidelines, feel free to get in touch with the core team.
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
The following rules should apply in all translations and can serve as a basis for your language-specific 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!
