[contributing] I18n onboarding doc

docs/contributing/community.md

@@ -27,8 +27,10 @@ The Gatsby community welcomes contributions. Please refer to the guides below on
 
 - [How to Contribute](/contributing/how-to-contribute/)
 - [How to File an Issue](/contributing/how-to-file-an-issue/)
+- [How to Open a Pull Request](/contributing/how-to-open-a-pull-request/)
 - [Make feature requests with an RFC](/blog/2018-04-06-introducing-gatsby-rfc-process/)
 - [Gatsby Style Guide](/contributing/gatsby-style-guide/)
+- [Gatsby Translations](/contributing/gatsby-docs-translation-guide/)
 
 ## Gatsby news
 

docs/contributing/gatsby-docs-translation-guide.md

@@ -0,0 +1,80 @@
+---
+title: Gatsby Docs Translation Guide
+---
+
+Since the [RFC on localization](https://github.com/gatsbyjs/rfcs/pull/42) for Gatsby, there is now 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 native speaker of a language other than English and you're interested in helping translate gatsbyjs.org, here is some information for you to know:
+
+## The general process
+
+Each translation has its own repository in the [gatsbyjs](https://github.com/gatsbyjs/) organization on GitHub, with designated codeowners to review and approve changes. 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](https://docs.google.com/spreadsheets/d/1u2amGnqFLKxJuL5h9UrDblUueFgg0EBt7xbau4n8iTM/edit) to get the most up-to-date priority list.
+
+## Use English as the source
+
+The [gatsbyjs.org](https://gatsbyjs.org) website is written in English and should be considered the source material for all translations (as opposed to translating from another translation). When a repository is created, it will provide the space to copy over prioritized docs and [make pull requests](/contributing/how-to-open-a-pull-request/) against them in the relevant language.
+
+## Process for starting a new translation
+
+The first step for starting a new translation is to check what exists. So far, there are repositories for the following languages:
+
+- [Spanish](https://github.com/gatsbyjs/gatsby-es)
+- [Russian](https://github.com/gatsbyjs/gatsby-ru)
+
+You can find the list of all translation requests here: https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aissue+%22New+Translation+Request%22+
+
+> Note: Once a new translation repository is created, feel free to add it here in a PR!
+
+### 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](https://help.github.com/en/articles/about-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](https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+%22New+Translation+Request%22) people have made and offer to join, or [get in touch with us](/contributing/how-to-contribute/#not-sure-how-to-start-contributing) at Gatsby for help in building your translation team.
+
+## Contributing to a translation
+
+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](/contributing/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 protected]](mailto:[email protected]) with details about the situation.
+
+### Code review process
+
+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).
+
+### 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.
+- 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)
+
+Additional tips:
+
+- Make a glossary and translation style guide. Here are some [examples from the React translation project](https://github.com/reactjs/reactjs.org-translation/blob/master/maintainer-guide.md#make-a-glossary-and-style-guide).
+- Collaborate on large or challenging pages. More than one person can contribute to a long tutorial or reference guide!
+- Set up a review process
+- Ask for help
+
+### Templates for responses on 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. Examples include:
+
+- PRs that don't meet expectations and need some work
+- ?
+
+## Which decisions are flexible? Which are firm guidelines?
+
+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 README file to set contributors up for success. Having trouble making decision? See above recommendations for settling disputes and working together.
+
+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](/blog/2019-04-19-gatsby-why-we-write/) with **high-quality spelling and grammar**, accurate information, similar structure and purpose. For any questions about guidelines, feel free to [get in touch](/contributing/how-to-contribute/#not-sure-how-to-start-contributing) with the Gatsby team.
+
+## Language-specific maintainer channels
+
+Each translation group may want to have a space for maintainers and community members to ask questions and coordinate the project. **[Discord](https://gatsby.dev/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](/contributing/how-to-contribute/#not-sure-how-to-start-contributing).

www/src/data/sidebars/contributing-links.yaml

@@ -26,6 +26,8 @@
       link: /contributing/code-of-conduct/
     - title: Gatsby Style Guide
       link: /contributing/gatsby-style-guide/
+    - title: Gatsby Docs Translation Guide
+      link: /contributing/gatsby-docs-translation-guide/
     - title: How to Contribute
       link: /contributing/how-to-contribute/
       items: