Gatsby Docs Translation Guide
There is an ongoing effort to translate the content on Gatsbyjs.org into multiple languages. For members of the community around the world building Gatsby sites and learning about web development, having docs and learning materials in your own language provides a lot of value. There’s also a great opportunity for folks like you to contribute to the translations of the Gatsby docs.
If you’re a fluent speaker of a language other than English and you’re interested in helping translate gatsbyjs.org, here is some information for you to know:
Each translation has its own repository in the gatsbyjs 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.
This doc will outline how to request a new language repository with its own team, what decisions each team can make, and suggestions for how you can work together.
The Gatsby learning team is in charge of determining priorities for which docs should be translated. Refer to the i18n page spreadsheet to get the most up-to-date priority list, which includes frequently-visited pages in the Gatsby docs, tutorial, recipes, and other important pages.
Reference guide overview pages are also worth translating to establish a fully translated path to a frequently visited reference guide, though they are listed at a lower priority. Pages not translated will appear in English alongside translated pages to present a complete website without gaps, similar to the React.js docs.
The gatsbyjs.org 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.
The first step for starting a new translation is to check what exists. So far, there are repositories for the following languages:
- Brazilian Portuguese
- Simplified Chinese
- Traditional Chinese
Note: Once a new translation repository is created, feel free to add it here in a PR!
If your language is not listed above, check the list of open translation requests.
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.
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, or get in touch with us at Gatsby for help in building your translation team.
Once a language repository is created and someone on the Gatsby 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.
Maintainers of a translation are expected to review translations for quality, friendly and encouraging tone of voice, and technical accuracy. These qualities should be considered in every pull request regardless of who it comes from; contributions should be encouraged from anyone in the community, not just maintainers.
⚠️ Note: All contributors are expected to follow the Gatsby Code of Conduct and work professionally with fellow contributors. For issues with conduct, if you are unable to work things out amicably amongst yourselves (perhaps after filing a public issue or having a discussion on Discord), you can contact the Gatsby team at email@example.com with details about the situation.
Translation contributions must be opened as pull requests to provide time for review and comments. If actionable feedback is given on a PR review, the author must acknowledge the review and make changes with their discretion. Ignoring review feedback completely is not allowed (see response templates below for help with this).
As repo maintainers and members of the Gatsby community, your responsibilities are as follows:
- Keep issues up-to-date as people volunteer to translate pages.
- Review pull requests made by contributors promptly.
- Review pull requests generated by gatsbybot in order to make sure translations remain up-to-date with the source repo. (details to come)
- Act as point of contact for your language and answer questions from both contributors to your language and the core Gatsby team.
- Set up a process in order to get your translation published. (details to come)
As a maintainer, you are welcome to add a contributing doc written in your language to assist with the process. You can find an example in the gatsby-es repo. Translating this page and copying it into a
contributing.md file would be an option as well.
Periodically, gatsbybot will create pull requests to keep translations repos up-to-date with the original English source. Make sure to review these PRs to ensure that your translation remains accurate.
Note: the bot doesn’t work yet but will come soon. Until then, see the next section to learn how to manually sync your repo.
If for whatever reason you’d like to manually sync your translation repo, you can do so by running these commands:
Fix all merge conflicts and create a pull request to finish the merge.
Some pages are very long and difficult to translate for a single contributor. Feel free to split these pages up into sections and work on them together!
In addition, sometimes a contributor cannot continue a PR for whatever reason. It may help to ask them if they need assistance and to bring someone else on to complete the work in a timely fashion.
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.
You have the ability to install any plugin or automation tool that will make your life easier as codeowners. Is there a text linter that works well in your language? Is there any automation that you can add? If you feel that these improvements would be beneficial to other languages as well, create an issue or PR for it in the main Gatsby repository.
Don’t be afraid to ask for help! If you’re not sure about something, you can post in the
#localization channel on the Gatsby Discord or create an issue in the Gatsby repo.
If it feels like there is too much work and you need help, you have the ability to to add more codeowners by editing the
CODEOWNERS file in the repo. Are there any contributors who are making exceptional contributions? If so, consider making them a codeowner.
We also understand that life sometimes gets in the way. If you find that you are no longer able to satisfy your codeowner duties, let the Gatsby team know so we can figure out the best path forward.
If you’re finding it hard to find people to help translate, spread the word about your translation effort! If you use social media like Twitter, tag the gatsby Twitter account and we’ll share it. Ask people in local Gatsby or React meetups if they would be interested in contributing.
Consistent with the Code of Conduct the Gatsby team reserves the right to remove a maintainer (or contributor) from the Gatsby organization if necessary. Some reasons for being removed include spammy comments, closing PRs or issues without action or productive dialogue,or generally harmful or abusive behavior inconsistent with Gatsby’s policies.
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.
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. Here is an example that can be translated for a given repo:
Because the main Gatsby repo is the source of content, more substantive changes should be closed and redirected there. Here is a template that could be translated for your repo:
Each language translation may have some specific ways it differs from the advice Gatsby provides for writing in English, such as the use of “you” as the pronoun or the Oxford comma. 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.
Guidelines that remain firm no matter the language stem from the goals and values of Gatsby as a project: to provide a friendly community for Gatsby learners of all skill and experience levels that’s also safe and welcoming to contributors. 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 Gatsby team.
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 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 gatsby repo so that all translations can benefit from the change.
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!
✅ ALSO OKAY:
❌ DEFINITELY DON’T:
Translate link text but keep all slugs and hashes in links the same as they are in English.
For links that have no equivalent (Stack Overflow, YouTube videos, etc.), use the English link.
Each translation group may want to have a space for maintainers and community members to ask questions and coordinate the project. Discord is the official channel and maintainers can have their own private groups if desired. Some groups may elect to use a different platform such as Wechat or Whatsapp, but that will be at your own discretion.
To set up a Discord channel for a translation group (if it doesn’t already exist), ping the Gatsbyjs team.
Edit this page on GitHub