From d913ab21660e4cfc5104c658767b992f114bec20 Mon Sep 17 00:00:00 2001 From: Mikhail Bashkirov Date: Wed, 31 Jul 2019 18:40:34 +0200 Subject: [PATCH] chore(localize): add rationale --- packages/localize/RATIONALE.md | 58 ++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 packages/localize/RATIONALE.md diff --git a/packages/localize/RATIONALE.md b/packages/localize/RATIONALE.md new file mode 100644 index 000000000..19746fb8d --- /dev/null +++ b/packages/localize/RATIONALE.md @@ -0,0 +1,58 @@ +# Rationale of the `localize` design + +## Requirements + +- loading translations per a web component or a module scope +- loading translations lazily +- loading translations from an API +- bundling and injecting translations for improving the initial page load time +- using variables in translations +- formatting dates and numbers according to a user's locale +- changing the language on the page without a full reload +- using JavaScript standards +- compatibility with modern tools like rollup and webpack +- backwards compatibility with Polymer CLI +- integration with lit-html and LitElement + +## Decision making + +### Building block of the localization system + +We chose ES modules as building blocks because: + +- this is a future proof standard +- support for loading both statically and dynamically +- good support in tools like rollup and webpack +- reusability of same translations between dialects of the same language + +We decided to split all translation data into immutable namespaces because: + +- there is a need for scopes to have a fine control over data +- namespaces can be loaded individually and bundled too (if needed) +- it is possible to consistently load all translations for a new language without full page reload (immutability is a key prerequisite here) + +### Localization of numbers and dates + +We decided to use `` as a source of truth for the locale value because: + +- this is a standard place in HTML +- it allows to support different tools like Google Chrome translate + +We chose `Intl MessageFormat` as a format for translation parts because: + +- it is the most stable solution for the web +- it is being standardized at the moment +- it supports formatting dates and numbers out of the box + +### Fallbacks + +We decided to have a fallback mechanism in case a dialect (e.g. `nl-NL.js`) is not defined, but generic language (e.g. `nl.js`) is, because we wanted to support legacy applications which used [Polymer's AppLocalizeBehavior](https://polymer-library.polymer-project.org/3.0/docs/apps/localize) and could not instantly switch to using full dialects. + +We decided to have a fallback locale (`en-GB` by default): + +- so that an app can work (with English where the gaps are) until everything is translated to all supported languages +- to allow Google Chrome translate feature to work and use a reliable source for translations when a user asks the page to be translated to an unsupported language + +### Switch statements in the loader functions + +We add switch statements to each of the loader functions to be backwards compatible with Polymer CLI.