Docs: add translation and proof reading guidelines

5 files changed, 138 insertions, 1 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 3096d9f25f0..fbe3b172826 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -65,7 +65,9 @@
 
 ## i18n
 
-- [Internationalization for GitLab](i18n_guide.md)
+- [Introduction](i18n/introduction.md)
+- [Externalization](i18n/externalization.md)
+- [Translation](i18n/translation.md)
 
 ## Compliance
 
diff --git a/doc/development/i18n_guide.md b/doc/development/i18n/externalization.md
index bd0ef39ca62..bd0ef39ca62 100644
--- a/doc/development/i18n_guide.md
+++ b/doc/development/i18n/externalization.md
diff --git a/doc/development/i18n/img/crowdin-editor.png b/doc/development/i18n/img/crowdin-editor.png
new file mode 100644
index 00000000000..5c31d8f0cec
--- /dev/null
+++ b/doc/development/i18n/img/crowdin-editor.png
diff --git a/doc/development/i18n/introduction.md b/doc/development/i18n/introduction.md
new file mode 100644
index 00000000000..a54b09359ce
--- /dev/null
+++ b/doc/development/i18n/introduction.md
@@ -0,0 +1,74 @@
+# Translate GitLab to your language
+
+The text in GitLab's user interface is in English by default.
+Each string can be translated to other languages.
+As each string is translated, it is added to the languages translation file,
+and will be available in future releases of GitLab.
+
+Contributions to translations are always needed.
+Many strings are not yet available for translation because they have not been externalized.
+Helping externalize strings benefits all languages.
+Some translations are incomplete or inconsistent.
+Translating strings will help complete and improve each language.
+
+## How to contribute
+
+### Externalize strings
+
+Before a string can be translated, it must be externalized.
+This is the process where English strings in the GitLab source code are wrapped in a function that
+retrieves the translated string for the users language.
+
+As new features are added and existing features are updated the surrounding strings are being
+externalized, however, there are many parts of GitLab that still need more work to externalize all
+strings.
+
+See [Externalization for GitLab](externalization.md).
+
+### Translate strings
+
+The translation process is managed at [translate.gitlab.com](https://translate.gitlab.com)
+using [Crowdin](https://crowdin.com/).
+You will need to create an account before you can submit translations.
+Once you are signed in, select the language you wish to contribute translations to.
+
+Voting for translations is also valuable, helping to confirm good and flag inaccurate translations.
+
+See [Translation guidelines](translation.md).
+
+### Proof reading
+
+Proof reading helps ensure the accuracy and consistency of translations.
+All translations are proof read before being accepted.
+If a translations requires changes, you will be notified with a comment explaining why.
+
+Community assistance proof reading translations is encouraged and appreciated.
+Requests to become a proof reader will be considered on the merits of previous translations.
+
+- Bulgarian
+- Chinese Simplified
+  - [Huang Tao](https://crowdin.com/profile/htve)
+- Chinese Traditional
+  - [Huang Tao](https://crowdin.com/profile/htve)
+- Chinese Traditional, Hong Kong
+  - [Huang Tao](https://crowdin.com/profile/htve)
+- Dutch
+- Esperanto
+- French
+- German
+- Italian
+- Japanese
+- Korean
+  - [Huang Tao](https://crowdin.com/profile/htve)
+- Portuguese, Brazilian
+- Russian
+  - [Alexy Lustin](https://crowdin.com/profile/lustin)
+  - [Nikita Grylov](https://crowdin.com/profile/nixel2007)
+- Spanish
+- Ukrainian
+
+If you would like to be added as a proof reader, please [open an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues) and add the `internationalization` label.
+
+### Release
+
+Translations are typically included in the next major or minor release.
diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md
new file mode 100644
index 00000000000..cc61eef2e87
--- /dev/null
+++ b/doc/development/i18n/translation.md
@@ -0,0 +1,61 @@
+# Translating GitLab
+
+For managing the translation process we use [Crowdin](https://crowdin.com).
+
+## Using Crowdin
+
+### Sign In
+
+To contribute translations at [translate.gitlab.com](https://translate.gitlab.com)
+you must create a Crowdin account.
+You may create a new account or use any of their supported sign in services.
+
+### Language Selections
+
+GitLab is being translated into many languages.
+
+1. Select the language you would like to contribute translations to by clicking the flag
+1. You will see a list of files and folders.
+  Click `gitlab.pot` top open the translation editor.
+
+### Translation Editor
+
+The online translation editor is the easiest way to contribute translations.
+
+![Crowdin Editor](img/crowdin-editor.png)
+
+1. Strings for translation are listed in the left panel
+1. Translations are entered into the central panel.
+  Multiple translations will be required for strings that contains plurals.
+  The string to be translated is shown above with glossary terms highlighted.
+  If the string to be translated is not clear, you can 'Request Context'
+
+A glossary of common terms is available in the right panel by clicking Terms.
+Comments can be added to discuss a translation with the community
+
+Remember to **Save** each translation.
+
+## Translation Guidelines
+
+### Technical terms
+
+Technical terms should be treated like proper nouns and not be translated.
+This helps maintain a logical connection and consistency between tools (e.g. `git` client) and
+GitLab.
+
+Technical terms that should always be in English are noted in the glossary when using
+[translate.gitlab.com](https://translate.gitlab.com).
+
+### Formality
+
+The level of formality used in software varies by language.
+For example, in French we translate `you` as the informal `tu`.
+
+You can refer to other translated strings and notes in the glossary to assist determining a
+suitable level of formality.
+
+### Updating the glossary
+
+To propose additions to the glossary please
+[open an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues).
+