Add guide to collaborate with i18ni18n-docs

5 files changed, 243 insertions, 11 deletions

diff --git a/doc/development/i18n_guide.md b/doc/development/i18n_guide.md
new file mode 100644
index 00000000000..72837542030
--- /dev/null
+++ b/doc/development/i18n_guide.md
@@ -0,0 +1,232 @@
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10669) in GitLab 9.2.
+
+## Internationalization for GitLab
+
+For working with internationalization (i18n) we use [GNU gettext](https://www.gnu.org/software/gettext/) given it's the most used tool for this task and we have a lot of applications that will help us to work with GNU gettext.
+
+
+## Tools
+
+We use a couple of gems:
+
+1. [gettext_i18n_rails](https://github.com/grosser/gettext_i18n_rails): this gem allow us to translate content from models, views and controllers. Also it give us access to the following rake tasks:
+
+- `rake gettext:find`: This script parse almost all the files from the Rails application and parse the content looking for content that have marked for translation. Finally it will update the PO files with the new content that it has found.
+
+- `rake gettext:pack`: This script process the PO files and generates the MO files that are binary files that are finally used by the application.
+
+2. [gettext_i18n_rails_js](https://github.com/webhippie/gettext_i18n_rails_js): this gem is useful to make the translations available in JavaScript. It provides the following script:
+
+- `rake gettext:po_to_json`: This script reads the contents from the PO files and generates JSON files containing all the available translations.
+
+3. PO editor: there are multiple applications that can help us to work with PO files, a good option is [Poedit](https://poedit.net/download) which is available for OS X, Linux and Windows.
+
+## Preparing a page for translation
+
+We basically have 4 types of files:
+
+1. Ruby files: basically Models and Controllers.
+1. HAML files: these are the view files.
+1. ERB files: these files are used for email templates.
+1. JavaScript files: we mostly need to work with VUE JS templates.
+
+#### Ruby files
+
+If we have a method or variable that works with a raw string, for instance:
+
+```
+def hello
+  "Hello world!"
+end
+```
+
+Or
+
+```
+hello = "Hello world!"
+```
+
+We can easily mark that content for translation with
+
+```
+def hello
+  _("Hello world!")
+end
+```
+
+Or
+
+```
+hello = _("Hello world!")
+```
+
+#### HAML files
+
+Given we have the following content in HAML:
+
+```
+%h1 Hello world!
+```
+
+We can mark that content for translation with:
+
+```
+%h1= _("Hello world!")
+```
+
+Sometimes there's some Vue.js content inside HAML files, for instance:
+
+```
+%span.not-available
+  {{ 'Not available' }}
+```
+
+We can mark that content for translation with:
+
+```
+%span.not-available
+  {{ __('Not available') }}
+```
+
+#### ERB files
+
+Given we have the following content in ERB:
+
+```
+<h1>Hello world!</h1>
+```
+
+We can mark that content for translation with:
+
+```
+<h1><%= _("Hello world!") %></h1>
+```
+
+#### JavaScript files
+
+In Javascript we added the `__()` function for translations, this is the same function we used before in the templates using Vue.js.
+
+### How to update the PO files with the new content
+
+Now that we have marked new content for translation we need to update the PO files, we can do it with the following command:
+
+```
+bundle exec rake gettext:find
+```
+
+This command will update the `locale/**/gitlab.edit.po` files with the
+new content that the parser has found.
+
+#### Working with special content
+
+##### Interpolation
+
+In Ruby/HAML:
+
+```
+_("Hello %{name}") % { name: 'Joe' }
+```
+
+In JavaScript:
+
+Not supported at this moment.
+
+##### Plurals
+
+In Ruby/HAML:
+
+```
+n_('Apple', 'Apples', 3) => 'Apples'
+```
+
+Using interpolation:
+
+```
+n_("There is a mouse.", "There are %{num} mice.", size) % { num: size }
+```
+
+In JavaScript files:
+
+```
+n__('Apple', 'Apples', 3) => 'Apples'
+```
+
+Using interpolation:
+```
+n__('Last day', 'Last %d days', 30) => 'Last 30 days'
+```
+
+##### Namespaces
+
+Sometimes we need to add some context to the text that we want to translate, basically you have to use it if the word occurs in a sentence, and/or the word is ambiguous.
+
+In Ruby/HAML:
+
+```ruby
+s_('OpenedNDaysAgo|Opened')
+```
+
+In case the translation is not found it will return `Open File`
+
+In JavaScript:
+
+```js
+s__('OpenedNDaysAgo|Opened')
+```
+
+##### Just marking content for parsing
+
+Sometimes we have some dynamic translations that can't be found by the
+parser when running the `bundle exec rake gettext:find` script, for
+these scenarios we can use the `_N` [method](https://github.com/grosser/gettext_i18n_rails#unfound-translations-with-rake-gettextfind).
+
+Messages from validation errors can also be translated using [this method](https://github.com/grosser/gettext_i18n_rails#option-a).
+
+## Adding a new language
+
+Let's suppose we want to add translations for a new language: French
+
+The first step is to register the new language in the `lib/gitlab/i18n.rb` file:
+
+```ruby
+...
+AVAILABLE_LANGUAGES = {
+  ...,
+  'fr' => 'Français'
+}.freeze
+...
+```
+
+And next we need to add the language with the following command:
+
+```sh
+bundle exec rake gettext:add_language[fr]
+```
+
+If we wanted to add a new language for a specific region the command is similar, we just need to separate the region with an `_` (underscore):
+
+```sh
+bundle exec rake gettext:add_language[en_gb]
+```
+
+Now that we have added the language a new directory has been created under the path: `locale/fr`
+
+Now we can start using our application for editing PO files, you need to open the file under the following path: `locale/fr/gitlab.edit.po`.
+
+After you're done updating the translations you need to process the PO files in order to generate the binary MO files and finally update the JSON files containing the translations. You need to use the following commands in order to do it:
+
+```sh
+bundle exec rake gettext:pack
+# and
+bundle exec rake gettext:po_to_json
+```
+
+Now in order to see our translated content we need to change our preferred language, it can be done in the **Settings** sections of our profile (/profile).
+
+After checking our changes are ok we can proceed to commit the new files:
+
+```
+git add locale/fr/ app/assets/javascripts/locale/fr/
+
+git commit -m "Add French translations for Cycle Analytics page"
+```
\ No newline at end of file
diff --git a/locale/de/gitlab.po b/locale/de/gitlab.po
index b804dc0436f..07587762edc 100644
--- a/locale/de/gitlab.po
+++ b/locale/de/gitlab.po
@@ -60,10 +60,10 @@ msgstr ""
 msgid "FirstPushedBy|pushed by"
 msgstr ""
 
-msgid "From issue creation until deploy to production"
+msgid "From merge request merge until deploy to production"
 msgstr ""
 
-msgid "From merge request merge until deploy to production"
+msgid "Hello"
 msgstr ""
 
 msgid "Introducing Cycle Analytics"
diff --git a/locale/en/gitlab.po b/locale/en/gitlab.po
index a43bafbbe28..3320f5ecf8a 100644
--- a/locale/en/gitlab.po
+++ b/locale/en/gitlab.po
@@ -60,10 +60,10 @@ msgstr ""
 msgid "FirstPushedBy|pushed by"
 msgstr ""
 
-msgid "From issue creation until deploy to production"
+msgid "From merge request merge until deploy to production"
 msgstr ""
 
-msgid "From merge request merge until deploy to production"
+msgid "Hello"
 msgstr ""
 
 msgid "Introducing Cycle Analytics"
diff --git a/locale/es/gitlab.po b/locale/es/gitlab.po
index c14ddd3b94c..f5e1b8d2abc 100644
--- a/locale/es/gitlab.po
+++ b/locale/es/gitlab.po
@@ -61,12 +61,12 @@ msgstr "Primer"
 msgid "FirstPushedBy|pushed by"
 msgstr "enviado por"
 
-msgid "From issue creation until deploy to production"
-msgstr "Desde la creación de la incidencia hasta el despliegue a producción"
-
 msgid "From merge request merge until deploy to production"
 msgstr "Desde la integración de la solicitud de fusión hasta el despliegue a producción"
 
+msgid "Hello"
+msgstr ""
+
 msgid "Introducing Cycle Analytics"
 msgstr "Introducción a Cycle Analytics"
 
diff --git a/locale/gitlab.pot b/locale/gitlab.pot
index 3967d40ea9e..d646dbcb99b 100644
--- a/locale/gitlab.pot
+++ b/locale/gitlab.pot
@@ -8,8 +8,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: gitlab 1.0.0\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2017-05-04 19:24-0500\n"
-"PO-Revision-Date: 2017-05-04 19:24-0500\n"
+"POT-Creation-Date: 2017-05-15 19:39-0500\n"
+"PO-Revision-Date: 2017-05-15 19:39-0500\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
 "Language: \n"
@@ -61,10 +61,10 @@ msgstr ""
 msgid "FirstPushedBy|pushed by"
 msgstr ""
 
-msgid "From issue creation until deploy to production"
+msgid "From merge request merge until deploy to production"
 msgstr ""
 
-msgid "From merge request merge until deploy to production"
+msgid "Hello"
 msgstr ""
 
 msgid "Introducing Cycle Analytics"