75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
# `$localize` Global Import Migration
|
|
|
|
## What does this schematic do?
|
|
|
|
If you're using i18n, this schematic adds an import statement for `@angular/localize` to `polyfills.ts` that will look something like this:
|
|
|
|
```ts
|
|
/******************************************************************
|
|
* Load `$localize` - used if i18n tags appear in Angular templates.
|
|
*/
|
|
import '@angular/localize/init';
|
|
```
|
|
|
|
It also lists `@angular/localize` as a dependency in your app's `package.json` to ensure the import is found.
|
|
|
|
```json
|
|
|
|
"dependencies": {
|
|
...
|
|
"@angular/localize": "...",
|
|
...
|
|
}
|
|
|
|
```
|
|
|
|
`@angular/localize` is a new package that supports i18n of messages in Ivy applications.
|
|
This package requires a global `$localize` symbol to exist.
|
|
The symbol is loaded by importing the `@angular/localize/init` module, which has the side-effect of attaching it to the global scope.
|
|
|
|
## Why is this migration necessary?
|
|
|
|
Prior to Angular version 9, Angular's internationalization (i18n) system inlined translated messages into the compiled output as part of this template compilation. This approach required running the template compiler once per target locale, often leading to slow production build times.
|
|
|
|
In the new i18n system, the Angular compiler tags i18n messages in the compiled code with a global `$localize` handler.
|
|
The inlining of translations then occurs as a post-compilation step for each locale.
|
|
Because the application does not need to be built again for each locale, this makes the process much faster.
|
|
|
|
The post-compilation inlining step is optional—for example during development or if the translations will be inlined at runtime.
|
|
Therefore this global `$localize` must be available on the global scope at runtime.
|
|
To make `$localize` available on the global scope, each application must now import the `@angular/localize/init` module.
|
|
This has the side-effect of attaching a minimal implementation of `$localize` to the global scope.
|
|
|
|
If this import is missing, you will see an error message like this:
|
|
|
|
```
|
|
Error: It looks like your application or one of its dependencies is using i18n.
|
|
Angular 9 introduced a global `$localize()` function that needs to be loaded.
|
|
Please run `ng add @angular/localize` from the Angular CLI.
|
|
(For non-CLI projects, add `import '@angular/localize/init';` to your polyfills.ts file)
|
|
```
|
|
|
|
This schematic automatically adds the `@angular/localize/init` import for you
|
|
if your app uses Angular's i18n APIs.
|
|
|
|
|
|
## Why is my tslint failing?
|
|
|
|
The import of `@angular/localize/init` may cause a tslint error for `no-import-side-effect` because it adds to the global context (that is, a side effect). To fix this error, add the following to your `tslint.config`:
|
|
|
|
```json
|
|
|
|
"no-import-side-effect": [
|
|
true,
|
|
{
|
|
"ignore-module": "(core-js/.*|zone\\.js/.*|@angular/localize/init)$"
|
|
}
|
|
]
|
|
|
|
```
|
|
|
|
|
|
## Do I need to change how I write i18n in my Angular templates?
|
|
|
|
The template syntax for i18n has not changed, so you will still want to use the `i18n` attribute as you did before.
|