monkey-style-guide 21.2.13 → 21.2.15

package/README.md

@@ -15,6 +15,49 @@ Run `ng build monkey-style-guide-v2` to build the project. The build artifacts w
 
 After building your library with `ng build monkey-style-guide-v2`, go to the dist folder `cd dist/monkey-style-guide-v2` and run `npm publish`.
 
+## Internationalization
+
+The library ships its own strings (`MonkeyDictionaryService`) in four buckets: `pt-BR`, `es-CL`,
+`es-MX` and `en-US`. `pt-BR` is the default and the per-key fallback.
+
+By default the active bucket comes from Angular's `LOCALE_ID`, which is fixed at bootstrap. Apps that
+resolve the language later (whitelabel/program config, a language switcher) should provide
+`MECX_I18N_LANG` and push every language change into it — the dictionary then re-renders mounted
+components without remounting them.
+
+```ts
+// app.config.ts
+const i18nLang$ = new BehaviorSubject<string>(env.locale.lang);
+
+providers: [
+  { provide: MECX_I18N_LANG, useValue: i18nLang$ },
+  { provide: LOCALE_ID, useValue: env.locale.lang }
+];
+```
+
+```ts
+// wherever the app switches language
+handleI18N(lang: string, obj?: any): void {
+  if (obj) { this._translateService.setTranslation(lang, obj, true); }
+  this._translateService.use(lang);
+  this._i18nLang.next(lang);
+}
+```
+
+When `MECX_I18N_LANG` is not provided the service behaves as before, reading `LOCALE_ID` once.
+
+Notes:
+
+- A language outside the four buckets falls back to `pt-BR` per key, never to blank labels. A new
+  language needs a full bucket — every key, including the nested `FILTER-BAR.DATE.*`,
+  `FILTER-BAR.OPERATOR.*` and `TABLE.ROW.*` groups — or the UI comes out mixed-language.
+- Overrides pushed through `MECX_I18N_WRAPPER` are merged into the bucket that is active when they
+  arrive, so push the new language into `MECX_I18N_LANG` **before** pushing its overrides.
+- This covers the dictionary only. `LOCALE_ID` also drives Angular's `date`, `currency`, `number` and
+  `percent` pipes, whose locale data is registered at bootstrap and cannot be swapped at runtime — so
+  a switched app can show pt-BR labels next to `MM/dd/yyyy` dates. Use `registerLocaleData` and a
+  reload for pipe formats.
+
 ## Running unit tests
 
 Run `ng test monkey-style-guide-v2` to execute the unit tests via [Karma](https://karma-runner.github.io).