summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Tang <dennis@dennistang.net>2018-06-12 12:29:52 +0000
committerDouwe Maan <douwe@gitlab.com>2018-06-12 12:29:52 +0000
commiteb9210df77bfa173792685b1d9c703c3bbf531a9 (patch)
tree25a2db44dc0ec56b0c9290555f61c9c9e83d3488
parent77247771c96307c2d68cae0cc7da576b2cee109c (diff)
downloadgitlab-ce-eb9210df77bfa173792685b1d9c703c3bbf531a9.tar.gz
i18n: document how to use links without splitting sentences
-rw-r--r--doc/development/i18n/externalization.md23
1 files changed, 22 insertions, 1 deletions
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index 0edcb23c7c5..4ba9958e2c6 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -233,7 +233,7 @@ This makes use of [`Intl.DateTimeFormat`].
Please never split a sentence as that would assume the sentence grammar and
structure is the same in all languages.
-For instance, the following
+For instance, the following:
```js
{{ s__("mrWidget|Set by") }}
@@ -247,6 +247,27 @@ should be externalized as follows:
{{ sprintf(s__("mrWidget|Set by %{author} to be merged automatically when the pipeline succeeds"), { author: author.name }) }}
```
+#### Avoid splitting sentences when adding links
+
+This also applies when using links in between translated sentences, otherwise these texts are not translatable in certain languages.
+
+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 }
+```
+
+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 }
+```
+
+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.
+
When in doubt, try to follow the best practices described in this [Mozilla
Developer documentation][mdn].