# `localeData` registration with `$locale`

[[TOOL-1109] Update i18n register localeData in ngtools/webpack for Ivy](https://angular-team.atlassian.net/browse/TOOL-1109)

# Work Breakdown
- [ ] [Manu] [ETA 11/1] Turn the work breakdown into Jira Issues after we agree upon them.
- [ ] [Pete] [ETA 11/1] Convert `@angular/common/locale/*` bundles to be true UMD such that they publish their content to `ng.common.locales.*`.
- [ ] JIRA : https://angular-team.atlassian.net/browse/FW-1657
- [ ] PR : https://github.com/angular/angular/pull/33523
- [ ] Follow up JIRA : https://angular-team.atlassian.net/browse/FW-1660
- [ ] [Pete] [ETA 11/3] Change `findLocaleData(locale: String)` to search `ng.common.locale.*` when retrieving `localeData` for the `locale`.
- [ ] JIRA : https://angular-team.atlassian.net/browse/FW-1657
- [ ] PR : https://github.com/angular/angular/pull/33523
- [ ] [Pete] [ETA 11/15] Change `localize-translate` to support asset translation. We would use that to insert the appropriate locale-data file.
- [ ] JIRA : https://angular-team.atlassian.net/browse/FW-1658
- [ ] Design : https://hackmd.io/QYT41Ay2SeqwHW7CSLm-0w.
- [ ] [Charles] Append the locale UMD bundle to the polyfill bundle and this ensures the sourceMap is not invalidated. Supercedes item below.
<s>- [ ] [Charles] Change the CLI to inject additional `@angular/common/locale/*` targets after the `localize-translate` is executed into the `main.js` bundle by pre-pending the desired `@angular/common/locale/*` UMD.
- [ ] PR : https://github.com/angular/angular-cli/pull/15989</s>
- [ ] [Filipe] [ETA 11/15] update cli-hello-world-ivy-i18n integration test to exercise locale data to prevents regression
- [ ] PR : https://github.com/angular/angular/pull/33510
- [ ] [Pete] [ETA 11/15] (*aside*) Update cli-hello-world-ivy-i18n integration test to use the full CLI integration for i18n (currently it is using the `localize-translation` binary) and create a separate integration test that does not use CLI.
- [ ] JIRA : https://angular-team.atlassian.net/browse/FW-1659
- [ ] PR (from Filipe) : https://github.com/angular/angular/pull/33510
- [ ] [Judy] Angular CLI usage docs for i18n

# Mental Model v2

1. `locale` as in translation of text and `localeData` as in formatting of currencies/dates is not the same thing. (For example you have multiple accounts at a bank with different currencies.) `localeData` is very processor specific (in our case `@angular/common` pipes etc...). As such `$localize` should not be responsible for such data unless `$localize` will also take on formatters (which would replace `@angular/common` pipes etc...)
2. Angular developers do expect that default `localeData` will be loaded for their `locale`. Because `$localize` is in the business of keeping track of `locale` and infusing it, it should also provide facility of conditionally inlining files based on `locale`. Keep in mind that `localize-translate` would be agnostic to the contents of these files. (Strawman)
- `localize-translate dirToTranslate --locale_inline=someFile_{}.js`
- > [name=Pete] - which file (in the `dirToTranslate`) would receive the inlined content?
- The above would then inline `someFile_fr.js` etc.. into the head of the file.
- NOTE: Such a flag would than give the developer option to include (or not) the `localData` based on application needs.
- Such facilities could then be used for other locale dependent uses.
3. In runtime version the developer would be responsible for loading their own `localeDate` along with the translation bundles. (This would also be true in the infused case, if the application needed additional formatting `localeData`)
4. The `@angular/common/locale` files would have to be re-done so that they are in UMD format and therefore inlineable to the existing files. They would then place the `localeData` content into a well know locations such as `ng.localeData`:

    if (typeof ng === 'undefine') window.ng = {};
    if (typeof ng.localeData === 'undefine') ng.localeData = {};
    ng.localeData['fr'] = [....];

`@angular/core` would than have to load them like so:

    if (typeof ng === 'undefine'){
      if (typeof ng.localeData === 'undefine') {
        Object.values(ng.localData).forEach(registerLocaleData);
      };
    
    }

> [name=Igor] the locale files are already in the umd format, see: https://unpkg.com/browse/@angular/common@9.0.0-next.14/locales/af-NA.js
> [name=Filipe Silva] They are UMD but do not auto-register on the global scope. They only provide require-style exports and AMD-style defines. Running this code in a browser leaves the locale data inacessible.

## File replacement approach:heart:

1. Change the locale files to attach themselves to the global scope (e.g. `ng.localeDate.xx`, where `xx` is the locale name).

   if (typeof ng === 'undefine') window.ng = {};
   if (typeof ng.localeData === 'undefine') ng.localeData = {};
   ng.localeData['fr'] = [....];

> [name=Miško Hevery] I don't think it should be `locale` as not to get confused with `$localize.locale` (but open to bike shedding).
2. Provide a locale to an application by loading it before bootstrap. For instance in a normal browser application it could be included via a script tag in index.html:

    <script src="locale.js"></script>

3. For compile time inlining, the `locale.js` file is replaced with contents of the appropriate locale data file.
For example, the locale files could be stored in a well defined folder: `locales/locale.en.js`, `locales/locale.fr.js` etc.
Then the locale data could be found by applying the target locale name (e.g. `locales/locale.${locale}.js`).

4. The `localize.translate` binary has a concept of `TranslationHandler`:

  interface TranslationHandler {
    canTranslate(relativeFilePath: string, contents: Buffer): boolean;
    translate(
      diagnostics: Diagnostics, sourceRoot: string, relativeFilePath: string, contents: Buffer,
      outputPathFn: OutputPathFn, translations: TranslationBundle[], sourceLocale?: string): void;
  }

A new handler could be developed that can match the `locale.js` file and search for an appropriate replacement. Then instead of just copying the file as-is (like the `AssetTranslationHandler` does) it would instead put the correct target file there.
(This could also be leveraged to provide things like image replacement.)
5. The default locale (e.g. `en`) would be provided in the normal `locale.js`, so if no compile-time inlining occurs, the locale data is already available.

> [name=Miško Hevery] How would we deal with filenames such as `locale_en-US.js`, `locale_en-UK.js`, etc...? Are we actually creating separate builds for `en-US` and `en-UK`? I guess we could `color` vs `colour`.
> [name=Pete] Currently there are `en` plus all the myriad of `en-XX` files in the locales folder.
**Do we expect translation locales to match locale-data locales?**
# DISCARDED: Mental Model v1

1. `$localize` is responsible for `localData`

   interface $localize {
     /**
      * Use: `$localize.localeData[$localize.locale]` to get the current
      * `localeData`.
      */
     localeData?: {[locale:string]: LocaleData};
   }

2. Keep in mind that while an application can be translated in only one locale, it is possible for the application to use multiple locales at runtime for formatting (dates, currencies, etc...; For example you have multiple accounts at a bank with different currencies.) As such the developer needs to be responsible for telling `$localize` which locales are required (We may simplify developer's life by pre-including the current locale)
2. By default no locale is shipped with `$localize`.
- *At Runtime*: The developer is responsible for loading the locale along with the translation data. The best way to do this is probably through UMD. (see options below).
- *Infused*: If `localize-translate` detects `$localize.localeData` reference than it will insert locale specific constant at the begging of code using a default locale.

    if (typeof $locale === 'undefine') window.$locale = {};
    if (typeof $locale.localeData === 'undefine') $locale.localeData = {};
    $locale.localeData['fr'] = [....];
    // rest of the source

(Remember the goal of `localize-transalate` is to completely remove `$localize` function from the source code. For this reason loading `localizeData` has to re-create the `$localez.localeData` in non-destructive way. This is also important since more locales may be loaded through UMD, and we have to ensure that the same UMD can work in both runtime and infused mode.
3. The application code can access the `localeDate` as follows `$localize.localeData[$localize.locale]`. The `localize-translate` would than replace it with the constant referenced in the above step as follow.
- replace `$localize.locale` with constant such as `"fr"`.

    alert($localize.localeData[$localize.locale][CURRENCY]);

would translate to

    // BEGIN inserted by `localize-translate`
    if (typeof $locale === 'undefine') window.$locale = {};
    if (typeof $locale.localeData === 'undefine') $locale.localeData = {};
    $locale.localeData['fr'] = [....];
    // END inserted by `localize-translate`

    alert($localize.localeData['fr'][CURRENCY]);

Notice that `$localize.locale` got inlined into `'fr'`.
4. `@angular/core` needs to be compatible with `$localize`. The implication is that we have to call `registerLocaleData` at bootstrap.

   registerLocaleData($localize.localeData);

This will be iterate over all of the locales and register them with `@angular/core`. Because `localize-translate` will auto include the translation locale automatically there is no additional step needed to be done by the application developer (An exception would be if the application would need to load additional locales for formatting).

*NOTE: backwards compatibility* [`getLocalePluralCase()`](https://github.com/angular/angular/blob/master/packages/core/src/i18n/locale_data_api.ts#L48) brings its own locale so absence of `$localize.localeData` is not an issue.

# ~~Option A: tree shaking~~

Include all of the locales like so:

if ($localize.locale === 'fr') registerLocaleData(localeFr);
if ($localize.locale === 'en') registerLocaleData(localeEn);

and so on. This should make it work in the dev mode. Once the `localize-translate` build step runs with `en` locale, it will be replaced with

if ('en' === 'fr') registerLocaleData(localeFr);
if ('en' === 'en') registerLocaleData(localeEn);

We can than statically analyze and realize that some `if` statements will never run where as others will always be true, and we can tree shake it. However the `localize-translate` tool runs after tree shaker so it will probably have to be smart enough to do it itself.

**PROS**:

**CONS**:
- `localize-translate` does not know how to do tree shaking, and so we would have to run tree shaker again on the resulting bundle. This is further complicated by the fact that WebPack could have put the different locales into separate chunks in which case we have no hope of tree shaking them.

# ~~Option B: `$localize.localeData`~~

`$localize` should be responsible for all things localizable, which should include `localeData`. Because it would be in specific format `localize-translate` would than be able to remove unneeded code without supporting full tree-shaking.

if ($localize.locale === 'fr') $localize['fr'] = {...};
if ($localize.locale === 'en') $localize['en'] = {...};

`localize-translate` would have to be intelligent enough to remove the whole `if` statement. Given that the data is inlined this should be sufficient.

**PROS**:
- Can be easily released as part of the RC by including all of the locales, a cleanup step can be released later.
- Default pass through implementation can be shipped with `en` locale only, which should suffice for most apps.

**CONS**:

- `localize-translate` is slowly getting into tree shaking business.
- Requires all possible locales to be known at application build time.
- Runtime localization would require manual loading of locales somehow.

# Option C: `$localize.localeData`

`$localize` should be responsible for all things localizable, which should include `localeData`. During the infuse step, `localize` accepts an `localeData` and `localeDataExtra` arguments for arbitrary data (maybe just JSON?) that it will include in the infusion process.

This data is then made available at runtime.

import {registerLocaleData} from '@angular/common';
registerLocaleData($localize.localeData, $localize.locale, $localize.localeDataExtra);

> [name=Miško Hevery] How would that work for runtime localization?
> [name=Filipe Silva] no idea, have not looked at that case. We could just put it there? `$localize.localeData = {}`

**PROS**:
- Usage pattern remains the same across consumers (build, then run localize)

**CONS**:

- Another transformation in localize.
- `localeData` and `localeDataExtra` may require more elaborate structure than just JSON which can be hard to infuse.

# Option D: import locale UMD

The build system adds includes each localeData (and any extra locale data) UMDs as a script before other scripts. The UMD exposes that locale data in `window`. It is then registered as before:

import { registerLocaleData } from '@angular/common';
registerLocaleData(window.localeData, $localize.locale, window.localeDataExtra);

> [name=Miško Hevery] The UMD should not be aware of `registerLocaleData` instead it should just do:
> ```typescript
> if (typeof $locale === 'undefine') window.$locale = {};
> if (typeof $locale.localeData === 'undefine') $locale.localeData = {};
> $locale.localeData['fr'] = [....];
> ```

**PROS**:
- can make use of current UMDs format for locale data

**CONS**:
- UMDs must be enhanced with global name registration
- unclear how to use with Universal

# Option E: use locale data JS scripts directly

The `@angular/common` package contains UMD files for each locale. These could be adjusted to register themselves with `$localize` upon execution. By including one or more of the scripts in the `index.html` for the application before the main application bundle files, the locale would automatically become registered. Universal can potentially bundle all known locales within the final bundle. The universal bundle is already quite large and does not need to be transferred to the client.

**PROS**:
- no need to alter the application bundles
- supports optionally including the "extra" locale data by including that script separately in the `index.html`

**CONS**:
- requires the standalone inliner to augment the application `index.html`
- additional files to deploy

---

# Brainstorming

Requirements:
- support both `locale` and `localeExtra`
- support browser and universal apps
> [name=Miško Hevery] Is that same just supporting runtime mode? or are there additional requirements?
> [name=Filipe Silva] should have the same support as AOT builds do today in CLI.
> [name=Alan] I'd say the only difference would be that like on the browser the local data can be as an external script on the server this is a bit trickier. Because the server is bundled into a single file which can run by itself. Meaning that "dist" can be shipped on the server and app will work both on the server and client. So during runtime we shouldn't assume the existance of node_modules.
>

- support cli and non-cli (e.g. bazel, basic integration tests, user setups) build pipelines
- Same source code should run in both runtime as well as compiled time mode.

## Design choices

*Runtime Localization*

We have two options:
1. Default implementation contains no `localeData` and it is up to the developer to include the right locals, etc...
- runtime localization requires loading of translation bundles, it is at that time that we should load the `localeData` as part of the translation.
- Implication is that the pass through needs to have some `localData` and having it be `en` seems presumptuous (plus it would need to be tree shaken).
> [name=Pete BD] Don't we already include the EN locale information by default in apps?
> [name=Misko Hevery] I don't believe so. What makes you think that we do?
> [name=Pete BD] Because the i18n pipes work out of the box?
> [name=Charles] Appears it is: https://github.com/angular/angular/blob/master/packages/core/src/i18n/locale_data_api.ts#L48
> [name=Misko Hevery] WAT! That is nuts!
> [name=Charles] The CLI now has a source locale option (default: `en-US`) which could allow the default inclusion to be removed. The CLI could instead automatically include the locale data defined in the source locale option as needed. This would be breaking for non-CLI builds though.
- By what mechanism should the `localeData` be included. UMD seems like a natural choice.
- > [name=Pete BD] - alternatively the locale file could add itself (side-effect-y) to the `$localize` global
- > [name=Filipe Silva] that is option E I think.
2. Include all localizations ahead of time and then tree shake them away.
- This seems like a lot of complex work which would be error prone.

*Compile-time Localization*

-

## Insights
- `$localize` should be the source of truth for `localeData`.
- `$localize` should ship with no `localeData` and it would be up to the developer to load the right locale.
- There should be a well know location for `localeData` such as `$localize.localeData`

## Short term plan for launching RC
- We can remove the migration to multi-locale builds in CLI and leave single-locale builds as exist today. These work with both VE and Ivy.

## Long term plan after RC