Merge branch 'master' into docs-patch-71docs-patch-71

2 files changed, 131 insertions, 106 deletions

diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index 9fb8ea542d9..141f5a8d6d9 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -21,18 +21,18 @@ The following tools are used:
 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 gives us access to the following raketasks:
-    - `rake gettext:find`: Parses almost all the files from the
-      Rails application looking for content that has been marked for
-      translation. Finally, it updates the PO files with the new content that
-      it has found.
-    - `rake gettext:pack`: Processes the PO files and generates the
-      MO files that are binary and are finally used by the application.
+   - `rake gettext:find`: Parses almost all the files from the
+     Rails application looking for content that has been marked for
+     translation. Finally, it updates the PO files with the new content that
+     it has found.
+   - `rake gettext:pack`: Processes the PO files and generates the
+     MO files that are binary and are finally used by the application.
 
 1. [`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 raketask:
-    - `rake gettext:po_to_json`: Reads the contents from the PO files and
-      generates JSON files containing all the available translations.
+   - `rake gettext:po_to_json`: Reads the contents from the PO files and
+     generates JSON files containing all the available translations.
 
 1. 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
@@ -77,6 +77,9 @@ Or:
 hello = _("Hello world!")
 ```
 
+NOTE: **Note:** Messages in the API (`lib/api/` or `app/graphql`) do
+not need to be externalised.
+
 ### HAML files
 
 Given the following content in HAML:
@@ -132,64 +135,65 @@ There is also and alternative method to [translate messages from validation erro
 ### Interpolation
 
 Placeholders in translated text should match the code style of the respective source file.
-For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript.
+For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make sure to [avoid splitting sentences when adding links](#avoid-splitting-sentences-when-adding-links).
 
 - In Ruby/HAML:
 
-    ```ruby
-    _("Hello %{name}") % { name: 'Joe' } => 'Hello Joe'
-    ```
+  ```ruby
+  _("Hello %{name}") % { name: 'Joe' } => 'Hello Joe'
+  ```
 
 - In JavaScript:
 
-    ```js
-    import { __, sprintf } from '~/locale';
+  ```js
+  import { __, sprintf } from '~/locale';
 
-    sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
-    ```
+  sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
+  ```
 
-    By default, `sprintf` escapes the placeholder values.
-    If you want to take care of that yourself, you can pass `false` as third argument.
+  By default, `sprintf` escapes the placeholder values.
+  If you want to take care of that yourself, you can pass `false` as third argument.
 
-    ```js
-    import { __, sprintf } from '~/locale';
+  ```js
+  import { __, sprintf } from '~/locale';
 
-    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is &lt;strong&gt;bold&lt;/strong&gt;'
-    sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>'
-    ```
+  sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }); // => 'This is &lt;strong&gt;bold&lt;/strong&gt;'
+  sprintf(__('This is %{value}'), { value: '<strong>bold</strong>' }, false); // => 'This is <strong>bold</strong>'
+  ```
 
 ### Plurals
 
 - In Ruby/HAML:
 
-    ```ruby
-    n_('Apple', 'Apples', 3)
-    # => 'Apples'
-    ```
+  ```ruby
+  n_('Apple', 'Apples', 3)
+  # => 'Apples'
+  ```
+
+  Using interpolation:
 
-    Using interpolation:
-    ```ruby
-    n_("There is a mouse.", "There are %d mice.", size) % size
-    # => When size == 1: 'There is a mouse.'
-    # => When size == 2: 'There are 2 mice.'
-    ```
+  ```ruby
+  n_("There is a mouse.", "There are %d mice.", size) % size
+  # => When size == 1: 'There is a mouse.'
+  # => When size == 2: 'There are 2 mice.'
+  ```
 
-    Avoid using `%d` or count variables in singular strings. This allows more natural translation in some languages.
+  Avoid using `%d` or count variables in singular strings. This allows more natural translation in some languages.
 
 - In JavaScript:
 
-    ```js
-    n__('Apple', 'Apples', 3)
-    // => 'Apples'
-    ```
+  ```js
+  n__('Apple', 'Apples', 3)
+  // => 'Apples'
+  ```
 
-    Using interpolation:
+  Using interpolation:
 
-    ```js
-    n__('Last day', 'Last %d days', x)
-    // => When x == 1: 'Last day'
-    // => When x == 2: 'Last 2 days'
-    ```
+  ```js
+  n__('Last day', 'Last %d days', x)
+  // => When x == 1: 'Last day'
+  // => When x == 2: 'Last 2 days'
+  ```
 
 ### Namespaces
 
@@ -199,17 +203,17 @@ Namespaces should be PascalCase.
 
 - In Ruby/HAML:
 
-    ```ruby
-    s_('OpenedNDaysAgo|Opened')
-    ```
+  ```ruby
+  s_('OpenedNDaysAgo|Opened')
+  ```
 
-    In case the translation is not found it will return `Opened`.
+  In case the translation is not found it will return `Opened`.
 
 - In JavaScript:
 
-    ```js
-    s__('OpenedNDaysAgo|Opened')
-    ```
+  ```js
+  s__('OpenedNDaysAgo|Opened')
+  ```
 
 Note: The namespace should be removed from the translation. See the [translation
 guidelines for more details](translation.md#namespaced-strings).
@@ -232,12 +236,12 @@ This makes use of [`Intl.DateTimeFormat`].
 - In Ruby/HAML, we have two ways of adding format to dates and times:
 
   1. **Through the `l` helper**, i.e. `l(active_session.created_at, format: :short)`. We have some predefined formats for
-  [dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261).
-  If you need to add a new format, because other parts of the code could benefit from it,
-  you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) file.
+     [dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261).
+     If you need to add a new format, because other parts of the code could benefit from it,
+     you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) file.
   1. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats
-  defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time
-  specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view).
+     defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time
+     specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view).
 
 ## Best practices
 
@@ -264,20 +268,41 @@ should be externalized as follows:
 
 This also applies when using links in between translated sentences, otherwise these texts are not translatable in certain languages.
 
-Instead of:
+- In Ruby/HAML, instead of:
 
-```haml
-- zones_link = link_to(s_('ClusterIntegration|zones'), 'https://cloud.google.com/compute/docs/regions-zones/regions-zones', target: '_blank', rel: 'noopener noreferrer')
-= s_('ClusterIntegration|Learn more about %{zones_link}').html_safe % { zones_link: zones_link }
-```
+  ```haml
+  - zones_link = link_to(s_('ClusterIntegration|zones'), 'https://cloud.google.com/compute/docs/regions-zones/regions-zones', target: '_blank', rel: 'noopener noreferrer')
+  = s_('ClusterIntegration|Learn more about %{zones_link}').html_safe % { zones_link: zones_link }
+  ```
 
-Set the link starting and ending HTML fragments as variables like so:
+  Set the link starting and ending HTML fragments as variables like so:
 
-```haml
-- zones_link_url = 'https://cloud.google.com/compute/docs/regions-zones/regions-zones'
-- zones_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: zones_link_url }
-= s_('ClusterIntegration|Learn more about %{zones_link_start}zones%{zones_link_end}').html_safe % { zones_link_start: zones_link_start, zones_link_end: '</a>'.html_safe }
-```
+  ```haml
+  - zones_link_url = 'https://cloud.google.com/compute/docs/regions-zones/regions-zones'
+  - zones_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: zones_link_url }
+  = s_('ClusterIntegration|Learn more about %{zones_link_start}zones%{zones_link_end}').html_safe % { zones_link_start: zones_link_start, zones_link_end: '</a>'.html_safe }
+  ```
+
+- In JavaScript, instead of:
+
+  ```js
+  {{
+      sprintf(s__("ClusterIntegration|Learn more about %{link}"), {
+          link: '<a href="https://cloud.google.com/compute/docs/regions-zones/regions-zones" target="_blank" rel="noopener noreferrer">zones</a>'
+      })
+  }}
+  ```
+
+  Set the link starting and ending HTML fragments as variables like so:
+
+  ```js
+  {{
+      sprintf(s__("ClusterIntegration|Learn more about %{linkStart}zones%{linkEnd}"), {
+          linkStart: '<a href="https://cloud.google.com/compute/docs/regions-zones/regions-zones" target="_blank" rel="noopener noreferrer">'
+          linkEnd: '</a>',
+      })
+  }}
+  ```
 
 The reasoning behind this is that in some languages words change depending on context. For example in Japanese は is added to the subject of a sentence and を to the object. This is impossible to translate correctly if we extract individual words from the sentence.
 
@@ -350,29 +375,29 @@ Let's suppose you want to add translations for a new language, let's say French.
 
 1. The first step is to register the new language in `lib/gitlab/i18n.rb`:
 
-    ```ruby
-    ...
-    AVAILABLE_LANGUAGES = {
-      ...,
-      'fr' => 'Français'
-    }.freeze
-    ...
-    ```
+   ```ruby
+   ...
+   AVAILABLE_LANGUAGES = {
+     ...,
+     'fr' => 'Français'
+   }.freeze
+   ...
+   ```
 
 1. Next, you need to add the language:
 
-    ```sh
-    bin/rake gettext:add_language[fr]
-    ```
+   ```sh
+   bin/rake gettext:add_language[fr]
+   ```
 
-    If you want to add a new language for a specific region, the command is similar,
-    you just need to separate the region with an underscore (`_`). For example:
+   If you want to add a new language for a specific region, the command is similar,
+   you just need to separate the region with an underscore (`_`). For example:
 
-    ```sh
-    bin/rake gettext:add_language[en_GB]
-    ```
+   ```sh
+   bin/rake gettext:add_language[en_GB]
+   ```
 
-    Please note that you need to specify the region part in capitals.
+   Please note that you need to specify the region part in capitals.
 
 1. Now that the language is added, a new directory has been created under the
    path: `locale/fr/`. You can now start using your PO editor to edit the PO file
@@ -382,9 +407,9 @@ Let's suppose you want to add translations for a new language, let's say French.
    in order to generate the binary MO files and finally update the JSON files
    containing the translations:
 
-    ```sh
-    bin/rake gettext:compile
-    ```
+   ```sh
+   bin/rake gettext:compile
+   ```
 
 1. In order to see the translated content we need to change our preferred language
    which can be found under the user's **Settings** (`/profile`).
@@ -392,7 +417,7 @@ Let's suppose you want to add translations for a new language, let's say French.
 1. After checking that the changes are ok, you can proceed to commit the new files.
    For example:
 
-    ```sh
-    git add locale/fr/ app/assets/javascripts/locale/fr/
-    git commit -m "Add French translations for Cycle Analytics page"
-    ```
+   ```sh
+   git add locale/fr/ app/assets/javascripts/locale/fr/
+   git commit -m "Add French translations for Cycle Analytics page"
+   ```
diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md
index 35c5b155594..492e3d48164 100644
--- a/doc/development/i18n/proofreader.md
+++ b/doc/development/i18n/proofreader.md
@@ -80,6 +80,7 @@ are very appreciative of the work done by translators and proofreaders!
 - Russian
   - Nikita Grylov - [GitLab](https://gitlab.com/nixel2007), [Crowdin](https://crowdin.com/profile/nixel2007)
   - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin)
+  - Mark Minakou - [GitLab](https://gitlab.com/sandzhaj), [Crowdin](https://crowdin.com/profile/sandzhaj)
   - NickVolynkin - [Crowdin](https://crowdin.com/profile/NickVolynkin)
 - Serbian (Cyrillic)
   - Proofreaders needed.
@@ -106,32 +107,31 @@ are very appreciative of the work done by translators and proofreaders!
 1. Contribute translations to GitLab. See instructions for
    [translating GitLab](translation.md).
 
-    Translating GitLab is a community effort that requires team work and
-    attention to detail. Proofreaders play an important role helping new
-    contributors, and ensuring the consistency and quality of translations.
-    Your conduct and contributions as a translator should reflect this before
-    requesting to be a proofreader.
+   Translating GitLab is a community effort that requires team work and
+   attention to detail. Proofreaders play an important role helping new
+   contributors, and ensuring the consistency and quality of translations.
+   Your conduct and contributions as a translator should reflect this before
+   requesting to be a proofreader.
 
 1. Request proofreader permissions by opening a merge request to add yourself
    to the list of proofreaders.
 
-    Open the [proofreader.md source file][proofreader-src] and click **Edit**.
+   Open the [proofreader.md source file][proofreader-src] and click **Edit**.
 
-    Add your language in alphabetical order, and add yourself to the list
-    including:
-    - name
-    - link to your GitLab profile
-    - link to your CrowdIn profile
+   Add your language in alphabetical order, and add yourself to the list
+   including:
+   - name
+   - link to your GitLab profile
+   - link to your CrowdIn profile
 
-    In the merge request description, please include links to any projects you
-    have previously translated.
+   In the merge request description, please include links to any projects you
+   have previously translated.
 
 1. Your request to become a proofreader will be considered on the merits of
    your previous translations by [GitLab team members](https://about.gitlab.com/team/)
    or [Core team members](https://about.gitlab.com/core-team/) who are fluent in
    the language or current proofreaders.
    - When a request is made for the first proofreader for a language and there are no [GitLab team members](https://about.gitlab.com/team/)
-   or [Core team members](https://about.gitlab.com/core-team/) who speak the language, we will request links to previous translation work in other communities or projects.  
-
+   or [Core team members](https://about.gitlab.com/core-team/) who speak the language, we will request links to previous translation work in other communities or projects.
 
 [proofreader-src]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/i18n/proofreader.md