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

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.

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 gatsby repo so that all translations can benefit from the change.

Use soft line wraps

Use soft line wraps for paragraphs:

✅ DO:

❌ DON’T:

Using soft line wraps ensures that paragraphs are always matched with the original source paragraphs when syncing, and prevents weird errors with mismatched lines.

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:

✅ ALSO OKAY:

❌ DON’T:

❌ DEFINITELY DON’T:

Translate link text but keep all slugs and hashes in links the same as they are in English.

✅ OK:

❌ DON’T:

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.

✅ OK:

For links that have no equivalent (Stack Overflow, YouTube videos, etc.), use the English link.

Edit this page on GitHub