Streamline GitLab UI components translation
Some GitLab UI components need to render labels. For example, GlSearchBoxByType
sets a placeholder
attribute on the input: https://gitlab.com/gitlab-org/gitlab-ui/-/blob/3f3985c85f99ab3ea5a838405ed429304fac1fe9/src/components/base/search_box_by_type/search_box_by_type.vue#L69.
When consuming those components, mainly in GitLab, we would like all labels to be translated. This means that any component that renders some text needs to make it customizable in some way. Up until now, there was no clear guideline as to how this should be done. The general approach has been to expose every label as a Vue prop. The default value would be some English label that appears in Storybook, and it would be the consumer's responsibility to provide the translated label whenever the component is used.
What's the problem?
The current approach as a few flaws.
Label props are optional
As stated above, all of those props have default values. This lets us use the components in Storybook without having to worry about passing labels in. This also means that, when consuming components anywhere else, it is extremely easy to forget that translated labels should be provided because our development environments are generally in English, and we won't worry about seeing the default non-translated labels being rendered.
It is pretty verbose
Having to expose a String
prop for every single label can get pretty verbose, both in GitLab UI and in the consumers. This might not be the best use of the props API.
It gets a bit crazy when composing components
Some of the most complex GitLab UI components render some of their siblings. Now if some of the child components render labels, the parent needs to re-expose the relevant props. This again is pretty easy to forget about due to those props being optional, and further increases verbosity. GlCollapsibleListbox
is a good example as its searchable variant renders GlSearchBoxByType
and therefore needs to expose the placeholder: https://gitlab.com/gitlab-org/gitlab-ui/-/blob/42696e211b8bc206a8d56de2138865441832a483/src/components/base/new_dropdowns/listbox/listbox.vue#L270.
How can we improve this?
This RFC intends to drop the props-based translation in favor of a configuration-based approach, along with a new utility component to override translations contextually.
- Reference implementation: gitlab-org/gitlab-ui!3414 (merged)
- Relevant page in the review app: http://poc-i18n.34.140.25.101.nip.io/?path=/docs/utilities-translation-provider--docs
The reference implementation provides some documentation for the proposed approach, please refer to the links above for most up-to-date information.
Here's a very brief TLDR:
- Mark labels as translatable via the
translate
method in GitLab UI. - Build and commit the
translations.json
dictionary which contains all supported translation keys and their default values (to be consumed when the consumer does not have translation capabilities). - In the consumer, provide generic translations to the
setConfig()
function. This build the primary source of translations for instances that don't need contextualized labels. - If needed, provide translation overrides by wrapping GitLab UI components within the new
GlTranslationProvider
component. This component basically accepts atranslations
object as a prop, validates it against the dictionary, andprovide
s the overridden labels to its children.