Skip to content

Expand i18n guidelines for Vue/frontend

Tom Quirk requested to merge tomquirk-master-patch-41754 into master

What does this MR do?

This MR changes the i18n guidance for frontend slightly. In particular, the language and tone of the doc has been changed to be more of a "soft guide" rather than a strict set of rules. This MR was inspired by !66036 (comment 627118158).

Link to current docs: https://docs.gitlab.com/ee/development/i18n/externalization.html#vue-files

Additionally:

  • some more context has been added around each of the suggested approaches
  • a bit of markdown/structural cleanup here and there

Why?

The current doc asserts that:

you should opt for this pattern, as this allows you to import these strings directly into your component specs for re-use during testing.

This works great for the alert/error messages where we should test the presence of the error message (e.g. in a createFlash, @error event emission, or GlAlert content)

However, in a Vue template where there are a reasonable amount (say, > 5) static strings with only one use-case, it feels cumbersome to move all of them to the $options object (or even further away from the template in a separate constants.js file. These are static, have a single usage and (usually) don't need to be tested. By moving them to a variable and to a separate file, we are creating 2 layers of abstraction from the Vue template that IMO makes the code harder to read (and makes it harder to change for unfamiliar contributors).

I can get behind consolidating strings into a single i18n object when there is a mixture of re-used and once-off strings in the template, but for templates where most/all the strings are static and used once, I feel we are creating variables just for the sake of it.

Hence, this documentation change proposal!

Edited by Tom Quirk

Merge request reports