xref: /openbmc/webui-vue/docs/guide/guidelines/internationalization.md (revision d2483622fc31f6b965a052d0c4f999ad963d0a0f) 
1# Internationalization
2
3The OpenBMC Web UI implements internationalization and separates the language-
4specific parts of the interface from the rest of the code, so they can be easily
5replaced. The OpenBMC Web UI uses the following library for
6internationalization:
7
8- [Vue I18n](https://kazupon.github.io/vue-i18n/introduction.html)
9
10## Key naming convention
11
12The OpenBMC Web UI follows the following key naming conventions:
13
14- Page specific labels should be nested in an object with a key prefixed `page`
15  followed by the page title. Formatting in this manner provides a systematic
16  structure and improves readability of the language file.
17  - e.g. `pageLocalUserManagement.editUser`
18- Any 'major' child components should be nested inside page specific objects
19  (ex. table, modal)
20  - e.g. `pageEventLogs.table.eventType`
21- Avoid any complex linked locale messages.
22- Alphabetize object keys. This helps in locating the keys.
23- We use the `$t()` function in markup and `this.$t` in scripts (which Vue I18n
24  provides to our components) for outputting translation messages.
25
26## Using the Vue I18n plugin
27
28- A new `src/i18n.js` file is added and it registers Vue I18n as a plugin to our
29  Vue instance via the `Vue.use()` function.
30- The CLI creates a `src/locales/en-US.json` file, which contains our default
31  translation messages.
32- The keys are placed in the `src/locales/en-US.json` file and then the `$t()`
33  function is used to output the translation messages.
34- After adding or removing calls to `$t` please run this to ensure consistent
35  English translation (note: using variable expansion in key names is not
36  handled automatically, you need to manually check them):
37
38```bash
39node node_modules/vue-i18n-extract/bin/vue-i18n-extract.js -v 'src/**/*.?(js|vue)' -l 'src/locales/en-US.json'
40```
41
42- If you're working on updating a translation for another language (e.g.
43  Russian), run this to see the omissions (as well as cruft) and add the
44  necessary keys automatically:
45
46```bash
47node node_modules/vue-i18n-extract/bin/vue-i18n-extract.js -v 'src/**/*.?(js|vue)' -l 'src/locales/ru-RU.json' -a
48```
49
50```json
51"pageDumps": {
52  "dumpsAvailableOnBmc": "Dumps available on BMC"
53}
54```
55
56```Vue
57<page-section :section-title="$t('pageDumps.dumpsAvailableOnBmc')">
58```
59
60- Vue I18n’s `$tc()` function can help with displaying plurals.
61  [Learn more about pluralization.](https://kazupon.github.io/vue-i18n/guide/pluralization.html)
62
63```json
64"modal": {
65  "deleteDump": "Delete dump | Delete dumps"
66}
67```
68
69```JS
70this.$bvModal
71  .msgBoxConfirm(this.$tc('pageDumps.modal.deleteDumpConfirmation'), {
72   title: this.$tc('pageDumps.modal.deleteDump'),
73   okTitle: this.$tc('pageDumps.modal.deleteDump'),
74   cancelTitle: this.$t('global.action.cancel'),
75   autoFocusButton: 'ok',
76  })
77```
78
79## Vendor overlays (environment-specific translations)
80
81To keep the base translation files vendor-neutral, vendor-specific strings live
82under `src/env/locales/<envName>/`.
83
84- Place shared vendor strings in the vendor root folder (e.g.,
85  `src/env/locales/vendor/`)
86- Place project-specific overrides in the variant folder when needed (e.g.,
87  `src/env/locales/vendor-variant/`)
88- Merge order at runtime:
89  1. Base locales from `src/locales/` (auto-discovered)
90  2. Vendor root overlays (e.g., `src/env/locales/vendor/`)
91  3. Variant overlays (e.g., `src/env/locales/vendor-variant/`)
92     - Variant keys overwrite vendor root keys on conflict
93
94Notes:
95
96- All JSON files under `src/locales/` are bundled automatically.
97- All JSON files under `src/env/locales/` that match the active environment are
98  also bundled.
99- If multiple vendor projects share strings, prefer the vendor root folder so
100  variants don’t duplicate content.
101
102Example: moving vendor-only dump type labels
103
104```json
105// src/locales/en-US.json (base)
106{
107  "pageDumps": {
108    "dumpTypes": {}
109  }
110}
111
112// src/env/locales/nvidia/en-US.json (overlay)
113{
114  "pageDumps": {
115    "dumpTypes": {
116      "hmcDump": "HMC dump",
117      "bmcDump": "BMC dump",
118      "systemBmcDump": "System [BMC] dump (disruptive)",
119      "systemHgxDump": "System [HGX] dump (disruptive)"
120    }
121  }
122}
123```
124
125### Locale codes
126
127We support aliasing short codes to our canonical locales:
128
129- `en` → `en-US`
130- `ru` → `ru-RU`
131- `zh` → `zh-CN`
132- `ka` → `ka-GE`
133
134If a short code is stored (e.g., in localStorage), it will be normalized at app
135startup.
136