Ease management of localisations (translations)
The objective is to centralise all localisations of all JS-based applications (DE, DLM, DV, ...) in a single default version of the related json configuration files and allow overwriting, when necessary, for specific instances or tenants and so ease the management of the translations.
Scenario
As a .Stat product manager as well as a translator
When I add or modify a localisation
Then
- I want to make this editing in only one single place as a default localisation, and automatically all tenants can reuse this localisation (Note: QA and STAGING environments keep separate configurations in order to support the agreed development process)
- I want to be able to overwrite the default localisation by a specific one per tenant/instance
- I want to easily identify obsolete keys to avoid uselessly managing those keys
Responsibilities:
- Devs are responsible for creating new localisation entries (keys) in the default English configuration, and removing there the obsolete default localisations when the related features are removed.
- PM team and ATF members are responsible for providing or entering the default or overwriting localisations (text) for all languages, including also adding/removing the keys in non-English localisations.
Benefits
This should avoid the time-consuming copying/pasting of localisations (like here) for the numerous staging tenants, ease setting and tracking translations by devs, reduce the files and localisations to maintain
@dosse @j3an-baptiste)
Documentation (draft to reviewconcepts
- default translations are used by all tenants in all apps
- a
<locale>.json
file is not restricted to a single app nor a single tenant anymore - config service is responsible to serve i18n files, ie default and override files
- consumers services (ie data-explorer, data-lifecycle-manager) handle on their backend translations reconciliation between default and overrides
overview
a translator deals with translation values, once per locale (that's enough!) and may override values for a tenant and an app.
a developer deals with nothing explicitly! if the update has an impact on translations keys, then 1 script should be run in the host app and 1 script in the config service before pushing changes from host app and config service in git.
translator
- a translator is a non-technical role responsible of filling values in translations files
- it only concerns the values of translations, not the keys (which are automatically managed) in default files
- it concerns existing keys in default as well as values in override files
how-to:
- go to config repo
- go to
./data/@(dev|prod)/i18n/<locale>.json
to update default translations values of<locale>
- go to
./data/@(dev|prod)/configs/<tenant>/<app>/i18n/<locale>.json
to override translations values of<locale>
in<app>
for<tenant>
developer
- a developer is a technical role (wait, what?) responsible of managing keys of default translations
- it only concerns keys of default translations (that's important as overridden keys is a user input)
how-to:
- go to data-explorer repo (0)
- update codebase with an impact on keys (ie add or remove, renaming a key is a add and a remove) (1)
- run
yarn i18n:extract
to extract keys of data-explorer in a temporarykeys.json
file at the root of the repo (2) - go to config repo
- run
yarn i18n:update data-explorer
to: (3) (4)- update default keys from data-explorer at
./data/default/i18n/data-explorer.json
(5) - update locales at
data/@(dev|prod)/i18n
(6) (7)
- update default keys from data-explorer at
notes:
- (0) only data-explorer supports the default translations today (beta test)
- (1) dynamic keys are not allowed, only statically defined keys are extractible
- (2) the file is ignored by git and overwritten by the script, leave it as is
- (3) the script expects to find the keys file in the adjacent dotstatsuite repo, use KEYS_PATH to override
- (4) the source (data-explorer) is required to handle key removal (if a key is removed from data-explorer, we have to check if the key is not used in another app before removing it from default keys)
- (5) handle by the script only and not ignored by git, don't touch it
- (6) only existing files are updated, the script discovers locales through files not with hardcoded var or a cmd arg that may unsync locales if not everything is updated at once
- (7) overrides are not covered by the automatic update, could be an evolution