Translation Maintainer Guide

⚠️ Note: At the moment our localization efforts are on pause, as we shifted towards a redesign of the docs. Right now, we’re prioritizing a new version of the tutorial. As with all prioritization efforts, we will weigh this, amongst other potential features, fixes, and improvements, and may consider picking up on the internationalization efforts of 2020. The repositories inside the GitHub org will remain. For now we archived the respective language channels on our Discord and the role for language maintainers.

This page lists the responsibilities of translation maintainers and provides tips on how to better manage your repository.

Maintainer responsibilities

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 files from the folder docs/contributing/translation and copying it into a contributing.md file would be an option as well.

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.

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.

Prioritize pages

The repo creation script will create a progress issue listing the list of core pages to translate. These are some of the most-used pages in Gatsby. 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.

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 overview pages are listed at a lower priority.

Ask for help

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 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.

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! 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.

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. Here is an example that can be translated for a given repo:

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. Here is a template that could be translated for your repo: