(docs) Split translation guide into multiple pages for clarity (#21254)

* Split up translation guide to separate articles

* fix links

* update maintainers guide

* whoops

docs/contributing/translation/index.md

@@ -0,0 +1,56 @@
+---
+title: Translating Gatsbyjs.org
+---
+
+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](https://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. 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.
+
+## Ongoing translations
+
+Currently, the following languages are being translated:
+
+- [Arabic](https://github.com/gatsbyjs/gatsby-ar)
+- [Bengali](https://github.com/gatsbyjs/gatsby-bn)
+- [German](https://github.com/gatsbyjs/gatsby-de)
+- [Spanish](https://github.com/gatsbyjs/gatsby-es)
+- [French](https://github.com/gatsbyjs/gatsby-fr)
+- [Gujarati](https://github.com/gatsbyjs/gatsby-gu)
+- [Hindi](https://github.com/gatsbyjs/gatsby-hi)
+- [Indonesian](https://github.com/gatsbyjs/gatsby-id)
+- [Italian](https://github.com/gatsbyjs/gatsby-it)
+- [Japanese](https://github.com/gatsbyjs/gatsby-ja)
+- [Korean](https://github.com/gatsbyjs/gatsby-ko)
+- [Mongolian](https://github.com/gatsbyjs/gatsby-mn)
+- [Dutch](https://github.com/gatsbyjs/gatsby-nl)
+- [Polish](https://github.com/gatsbyjs/gatsby-pl)
+- [Brazilian Portuguese](https://github.com/gatsbyjs/gatsby-pt-BR)
+- [Russian](https://github.com/gatsbyjs/gatsby-ru)
+- [Turkish](https://github.com/gatsbyjs/gatsby-tr)
+- [Vietnamese](https://github.com/gatsbyjs/gatsby-vi)
+- [Simplified Chinese](https://github.com/gatsbyjs/gatsby-zh-Hans)
+- [Traditional Chinese](https://github.com/gatsbyjs/gatsby-zh-Hant)
+
+> Note: Once a new translation repository is created, feel free to add it here in a PR!
+
+## Creating a new translation
+
+If you don't see your language in the above list, please see [Starting a new language](/contributing/translation/new-translations/) for how to start up a new translation repository.
+
+## Contributing translations
+
+If you do see your language on the list, please see the [translation contributor guide](/contributing/translation/translators/) 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. Please see the [Translation Maintainer Guide](/contributing/translation/maintainers/) 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. **[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).

docs/contributing/translation/maintainers.md

@@ -0,0 +1,87 @@
+---
+title: Translation Maintainer Guide
+---
+
+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](/contributing/translation/sync-guide/) 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](https://github.com/gatsbyjs/gatsby-es/blob/master/CONTRIBUTING.MD). Translating [this page](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/gatsby-docs-translation-guide.md) 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](https://github.com/gatsbyjs/gatsby-i18n-source/blob/master/style-guide.md) that you can use to put in style rules specific to your language. Refer to the [translation style guide](#translation-style-guide) section 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](https://github.com/gatsbyjs/gatsby/blob/master/scripts/i18n/pages.json). 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](https://docs.google.com/spreadsheets/d/1u2amGnqFLKxJuL5h9UrDblUueFgg0EBt7xbau4n8iTM/edit) 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](/contributing/docs-templates/#reference-guide-overview) are also worth translating to establish a fully translated path to a frequently visited [reference guide](/contributing/docs-templates/#reference-guides), though they 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](https://gatsby.dev/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.
+
+### 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](https://twitter.com/gatsbyjs) 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:
+
+```text
+Hey! Thanks so much for opening a pull request!
+
+We really appreciate you sending this over, but the change you’ve proposed is not going to be accepted because it doesn't meaningfully translate the Gatsby docs content.
+
+We absolutely want to have you as a contributor, so please take a look at [our open issues][open-issues] for ideas and reach out to the Gatsby team [on Twitter at @gatsbyjs](https://twitter.com/gatsbyjs) with questions.
+
+Thanks again, and we look forward to seeing more PRs from you in the future! 💪💜
+[open-issues]: YOUR_REPO_ISSUE_URL_HERE
+```
+
+### 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:
+
+```text
+Hey! Thanks so much for opening a pull request!
+
+We really appreciate you sending this over, but the change you’ve proposed is not going to be accepted because it includes broad changes to the docs content that should be done in the [main Gatsby repo](https://github.com/gatsbyjs/gatsby) instead.
+
+We absolutely want to have you as a contributor, so please take a look at the original source for these changes and make them there first before translating. You can also visit [our open issues][open-issues] for ideas and reach out to the Gatsby team [on Twitter at @gatsbyjs](https://twitter.com/gatsbyjs) with questions.
+
+Thanks again, and we look forward to seeing more PRs from you in the future! 💪💜
+[open-issues]: YOUR_REPO_ISSUE_URL_HERE
+```

docs/contributing/translation/new-translations.md

@@ -0,0 +1,37 @@
+---
+title: Starting a New Translation
+---
+
+This page lists the steps to take to create a a new Gatsbyjs.org translation.
+
+## Creating a translation
+
+### Read the maintainer guide
+
+Before requesting a new translation, make sure to read the [maintainer responsibilities](/contributing/translation/maintainers/#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](https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+%22New+Translation+Request%22). 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](https://github.com/gatsbyjs/gatsby/issues/new?template=new_translation.md) 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](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.
+
+## Criteria for translation approval
+
+The Gatsby team will choose to approve a translation request 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 gatsby team will run the an automated script to create your repository and set everything up.
+
+At this point, you and your co-maintainers should read the rest of the [maintainer guide](/contributing/translation/maintainers/) for more information on how to manage your translation repository. You can also check out the [translation contributor guide](/contributing/translation/translators/) for information on contributing translations to your own repo, and start working on your translation [style guide](/contributing/translation/style-guide/).

docs/contributing/translation/style-guide.md

@@ -0,0 +1,94 @@
+---
+title: Translation Style Guide
+---
+
+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](https://github.com/gatsbyjs/gatsby-i18n-source/blob/master/style-guide.md) file to set contributors up for success. Use the [English style guide](/contributing/gatsby-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](/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.
+
+### Glossary
+
+The style guide has a [glossary section](https://github.com/gatsbyjs/gatsby-i18n-source/blob/master/style-guide.md#glossary) that you can use to fill in common translations. Look at the English [Glossary](/docs/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 [gatsby repo](https://github.com/gatsbyjs/gatsby) 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!
+
+✅ DO:
+
+```jsx
+// Ejemplo
+import React from "react"
+export default () => (
+  <div style={{ color: `purple`, fontSize: `72px` }}>Hello Gatsby!</div>
+)
+```
+
+✅ ALSO OKAY:
+
+```jsx
+// Ejemplo
+import React from "react"
+export default () => (
+  <div style={{ color: `purple`, fontSize: `72px` }}>¡Hola Gatsby!</div>
+)
+```
+
+❌ DON'T:
+
+```jsx
+// Ejemplo
+import React from "react"
+export default () => (
+  // 'purple' is a CSS keyword
+  <div style={{ color: `morado`, fontSize: `72px` }}>¡Hola Gatsby!</div>
+)
+```
+
+❌ DEFINITELY DON'T:
+
+```jsx
+importar Reaccionar desde "reaccionar"
+exportar defecto () => (
+   <div estilo = {{color: `morado`, fontSize:` 72px`}}> ¡Hola Gatsby! </div>
+)
+```
+
+#### Internal links
+
+Translate link text but keep all slugs and hashes in links the same as they are in English.
+
+✅ OK:
+
+```markdown
+- [Configure su entorno de desarrollo](/tutorial/set-up-your-development-environment)
+```
+
+❌ DON'T:
+
+```markdown
+- [Configura tu entorno de desarrollo](/tutorial/configura-tu-entorno-de-desarrollo)
+```
+
+#### External links
+
+If an external link is to an article in a reference like [MDN] or [Wikipedia], and a version of that article exists in your language that is of decent quality, consider linking to that version instead.
+
+[mdn]: https://developer.mozilla.org/en-US/
+[wikipedia]: https://en.wikipedia.org/wiki/Main_Page
+
+✅ OK:
+
+```markdown
+Los elementos de React son [inmutables](https://es.wikipedia.org/wiki/Objeto_inmutable).
+```
+
+For links that have no equivalent (Stack Overflow, YouTube videos, etc.), use the English link.

docs/contributing/translation/sync-guide.md

@@ -0,0 +1,19 @@
+---
+title: Keeping Translations Up-to-date
+issue: https://github.com/gatsbyjs/gatsby/issues/21250
+---
+
+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.
+
+### Manually syncing translation repos
+
+If for whatever reason you'd like to manually sync your translation repo, you can do so by running these commands:
+
+```shell
+git remote add source https://github.com/gatsbyjs/gatsby-i18n-source.git
+git pull source master
+```
+
+Fix all [merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line) and create a pull request to finish the merge.