Commit 818374b9 authored by Mark Florian's avatar Mark Florian Committed by Ezekiel Kigbo

Update docs about sprintf vs GlSprintf usage

Also:
- Fix a broken link to the GlSprintf documentation page.
- Pass `false` as the third argument to `sprintf` in the JS-without-Vue
  examples which interpolate HTML. Without this argument, the examples
  won't work as expected.
parent a162a0aa
......@@ -255,7 +255,44 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make s
- In Vue:
See the section on [Vue component interpolation](#vue-components-interpolation).
Use the [`GlSprintf`](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/utilities-sprintf--sentence-with-link) component if:
- you need to include child components in the translation string.
- you need to include HTML in your translation string.
- you are using `sprintf` and need to pass `false` as the third argument to
prevent it from escaping placeholder values.
For example:
```html
<gl-sprintf :message="s__('ClusterIntegration|Learn more about %{linkStart}zones%{linkEnd}')">
<template #link="{ content }">
<gl-link :href="somePath">{{ content }}</gl-link>
</template>
</gl-sprintf>
```
In other cases it may be simpler to use `sprintf`, perhaps in a computed
property. For example:
```html
<script>
import { __, sprintf } from '~/locale';
export default {
...
computed: {
userWelcome() {
sprintf(__('Hello %{username}'), { username: this.user.name });
}
}
...
}
</script>
<template>
<span>{{ userWelcome }}</span>
</template>
```
- In JavaScript (when Vue cannot be used):
......@@ -265,12 +302,10 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. Make s
sprintf(__('Hello %{username}'), { username: 'Joe' }); // => 'Hello Joe'
```
If you want to use markup within the translation and are using Vue, you
**must** use the [`gl-sprintf`](#vue-components-interpolation) component. If
for some reason you cannot use Vue, use `sprintf` and stop it from escaping
placeholder values by passing `false` as its third argument. You **must**
escape any interpolated dynamic values yourself, for instance using
`escape` from `lodash`.
If you need to use markup within the translation, use `sprintf` and stop it
from escaping placeholder values by passing `false` as its third argument.
You **must** escape any interpolated dynamic values yourself, for instance
using `escape` from `lodash`.
```javascript
import { escape } from 'lodash';
......@@ -632,7 +667,7 @@ This also applies when using links in between translated sentences, otherwise th
{{
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>'
})
}, false)
}}
```
......@@ -643,7 +678,7 @@ This also applies when using links in between translated sentences, otherwise th
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>',
})
}, false)
}}
```
......@@ -652,45 +687,6 @@ The reasoning behind this is that in some languages words change depending on co
When in doubt, try to follow the best practices described in this [Mozilla
Developer documentation](https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Splitting).
##### Vue components interpolation
When translating UI text in Vue components, you might want to include child components inside
the translation string.
You could not use a JavaScript-only solution to render the translation,
because Vue would not be aware of the child components and would render them as plain text.
For this use case, you should use the `gl-sprintf` component which is maintained
in **GitLab UI**.
The `gl-sprintf` component accepts a `message` property, which is the translatable string,
and it exposes a named slot for every placeholder in the string, which lets you include Vue
components easily.
Assume you want to print the translatable string
`Pipeline %{pipelineId} triggered %{timeago} by %{author}`. To replace the `%{timeago}` and
`%{author}` placeholders with Vue components, here's how you would do that with `gl-sprintf`:
```html
<template>
<div>
<gl-sprintf :message="__('Pipeline %{pipelineId} triggered %{timeago} by %{author}')">
<template #pipelineId>{{ pipeline.id }}</template>
<template #timeago>
<timeago :time="pipeline.triggerTime" />
</template>
<template #author>
<gl-avatar-labeled
:src="pipeline.triggeredBy.avatarPath"
:label="pipeline.triggeredBy.name"
/>
</template>
</gl-sprintf>
</div>
</template>
```
For more information, see the [`gl-sprintf`](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-sprintf--default) documentation.
## Updating the PO files with the new content
Now that the new content is marked for translation, we need to update
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment