Skip to content
Permalink
Browse files

feat(ivy): i18n - reorganize entry-points for better reuse (#32488)

This is a refactoring that moves the source code around to provide a better
platform for adding the compile-time inlining.

1. Move the global side-effect import from the primary entry-point to a
   secondary entry-point @angular/localize/init.

   This has two benefits: first it allows the top level entry-point to
   contain tree-shakable shareable code; second it gives the side-effect
   import more of an "action" oriented name, which indicates that importing
   it does something tangible

2. Move all the source code into the top src folder, and import the localize
   related functions into the localize/init/index.ts entry-point.

   This allows the different parts of the package to share code without
   a proliferation of secondary entry-points (i.e. localize/utils).

3. Avoid publicly exporting any utilities at this time - the only public
   API at this point are the global `$localize` function and the two runtime
   helpers `loadTranslations()` and `clearTranslations()`.
   This does not mean that we will not expose additional helpers for 3rd
   party tooling in the future, but it avoid us preemptively exposing
   something that we might want to change in the near future.

Notes:

It is not possible to have the `$localize` code in the same Bazel package
as the rest of the code. If we did this, then the bundled `@angular/localize/init`
entry-point code contains all of the helper code, even though most of it is not used.

Equally it is not possible to have the `$localize` types (i.e. `LocalizeFn`
and `TranslateFn`) defined in the `@angular/localize/init` entry-point because
these types are needed for the runtime code, which is inside the primary
entry-point. Importing them from `@angular/localize/init` would run the
side-effect.

The solution is to have a Bazel sub-package at `//packages/localize/src/localize`
which contains these types and the `$localize` function implementation.
The primary `//packages/localize` entry-point imports the types without
any side-effect.
The secondary `//packages/localize/init` entry-point imports the `$localize`
function and attaches it to the global scope as a side-effect, without
bringing with it all the other utility functions.

BREAKING CHANGES:

The entry-points have changed:

* To attach the `$localize` function to the global scope import from
`@angular/localize/init`. Previously it was `@angular/localize`.

* To access the `loadTranslations()` and `clearTranslations()` functions,
import from `@angular/localize`. Previously it was `@angular/localize/run_time`.

PR Close #32488
  • Loading branch information...
petebacondarwin authored and kara committed Aug 10, 2019
1 parent e82f56b commit 2bf5606bbeb7e40506e467dd371e23f91e2815c0
Showing with 639 additions and 286 deletions.
  1. +1 −1 integration/cli-hello-world-ivy-i18n/src/polyfills.ts
  2. +1 −1 integration/side-effects/snapshots/core/esm2015.js
  3. +1 −1 integration/side-effects/snapshots/core/esm5.js
  4. +1 −1 modules/benchmarks/src/expanding_rows/BUILD.bazel
  5. +1 −1 modules/benchmarks/src/expanding_rows/index_aot.ts
  6. +1 −1 packages/core/src/core.ts
  7. +1 −1 packages/core/src/render3/i18n.md
  8. +1 −1 packages/core/test/BUILD.bazel
  9. +1 −1 packages/core/test/acceptance/BUILD.bazel
  10. +4 −2 packages/core/test/acceptance/i18n_spec.ts
  11. +1 −1 packages/core/test/acceptance/view_container_ref_spec.ts
  12. +2 −1 packages/core/test/bundling/hello_world_i18n/BUILD.bazel
  13. +4 −2 packages/core/test/bundling/hello_world_i18n/translations.ts
  14. +2 −1 packages/core/test/bundling/todo_i18n/BUILD.bazel
  15. +0 −3 packages/core/test/bundling/todo_i18n/index.ts
  16. +4 −7 packages/core/test/bundling/todo_i18n/todo_e2e_spec.ts
  17. +4 −2 packages/core/test/bundling/todo_i18n/translations.ts
  18. +3 −1 packages/core/test/linker/ng_container_integration_spec.ts
  19. +3 −2 packages/localize/BUILD.bazel
  20. +4 −68 packages/localize/index.ts
  21. +3 −3 packages/localize/{run_time → init}/BUILD.bazel
  22. +76 −0 packages/localize/init/index.ts
  23. +11 −0 packages/localize/init/package.json
  24. +3 −1 packages/localize/{run_time/index.ts → localize.ts}
  25. +7 −3 packages/localize/package.json
  26. +0 −12 packages/localize/run_time/package.json
  27. +0 −161 packages/localize/run_time/src/translate.ts
  28. +16 −0 packages/localize/src/localize/BUILD.bazel
  29. +9 −0 packages/localize/src/localize/index.ts
  30. 0 packages/localize/src/{ → localize/src}/global.ts
  31. 0 packages/localize/src/{ → localize/src}/localize.ts
  32. +1 −2 packages/localize/{run_time → src/localize}/test/BUILD.bazel
  33. +1 −2 packages/localize/{ → src/localize}/test/localize_spec.ts
  34. +57 −0 packages/localize/src/translate.ts
  35. +19 −0 packages/localize/src/utils/constants.ts
  36. +81 −0 packages/localize/src/utils/messages.ts
  37. +97 −0 packages/localize/src/utils/translations.ts
  38. +1 −0 packages/localize/test/BUILD.bazel
  39. +1 −2 packages/localize/{run_time → }/test/translate_spec.ts
  40. +47 −0 packages/localize/test/utils/messages_spec.ts
  41. +164 −0 packages/localize/test/utils/translations_spec.ts
  42. +2 −1 test-main.js
  43. +3 −0 tools/public_api_guard/localize/localize.d.ts
@@ -84,7 +84,7 @@ import 'zone.js/dist/zone'; // Included with Angular CLI.
/***************************************************************************************************
* Load `$localize` onto the global scope - used if i18n tags appear in Angular templates.
*/
import '@angular/localize';
import '@angular/localize/init';

/***************************************************************************************************
* APPLICATION IMPORTS
@@ -13,5 +13,5 @@ const __global = "undefined" !== typeof global && global;
const _global = __globalThis || __global || __window || __self;

if (ngDevMode) _global.$localize = _global.$localize || function() {
throw new Error("It looks like your application or one of its dependencies is using i18n.\n" + "Angular 9 introduced a global `$localize()` function that needs to be loaded.\n" + "Please add `import '@angular/localize';` to your polyfills.ts file.");
throw new Error("It looks like your application or one of its dependencies is using i18n.\n" + "Angular 9 introduced a global `$localize()` function that needs to be loaded.\n" + "Please add `import '@angular/localize/init';` to your polyfills.ts file.");
};
@@ -15,5 +15,5 @@ var __global = "undefined" !== typeof global && global;
var _global = __globalThis || __global || __window || __self;

if (ngDevMode) _global.$localize = _global.$localize || function() {
throw new Error("It looks like your application or one of its dependencies is using i18n.\n" + "Angular 9 introduced a global `$localize()` function that needs to be loaded.\n" + "Please add `import '@angular/localize';` to your polyfills.ts file.");
throw new Error("It looks like your application or one of its dependencies is using i18n.\n" + "Angular 9 introduced a global `$localize()` function that needs to be loaded.\n" + "Please add `import '@angular/localize/init';` to your polyfills.ts file.");
};
@@ -14,7 +14,7 @@ ng_module(
"//packages:types",
"//packages/common",
"//packages/core",
"//packages/localize",
"//packages/localize/init",
"//packages/platform-browser",
"@npm//rxjs",
],
@@ -6,7 +6,7 @@
* found in the LICENSE file at https://angular.io/license
*/
// This benchmark uses i18n in its `ExpandingRowSummary` component so `$localize` must be loaded.
import '@angular/localize';
import '@angular/localize/init';
import {enableProdMode} from '@angular/core';
import {platformBrowser} from '@angular/platform-browser';

@@ -47,6 +47,6 @@ if (ngDevMode) {
throw new Error(
'It looks like your application or one of its dependencies is using i18n.\n' +
'Angular 9 introduced a global `$localize()` function that needs to be loaded.\n' +
'Please add `import \'@angular/localize\';` to your polyfills.ts file.');
'Please add `import \'@angular/localize/init\';` to your polyfills.ts file.');
};
}
@@ -1052,7 +1052,7 @@ The generated code needs work with:
The solution is to take advantage of compile time constants (e.g. `CLOSURE`) like so:

```typescript
import '@angular/localize';
import '@angular/localize/init';
let MSG_hello;
if (CLOSURE) {
@@ -27,7 +27,7 @@ ts_library(
"//packages/core/src/reflection",
"//packages/core/src/util",
"//packages/core/testing",
"//packages/localize",
"//packages/localize/init",
"//packages/platform-browser",
"//packages/platform-browser-dynamic",
"//packages/platform-browser/animations",
@@ -20,7 +20,7 @@ ts_library(
"//packages/core/src/util",
"//packages/core/testing",
"//packages/localize",
"//packages/localize/run_time",
"//packages/localize/init",
"//packages/platform-browser",
"//packages/platform-browser-dynamic",
"//packages/platform-browser/animations",
@@ -5,13 +5,15 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
import '@angular/localize';
// Make the `$localize()` global function available to the compiled templates, and the direct calls
// below. This would normally be done inside the application `polyfills.ts` file.
import '@angular/localize/init';
import {registerLocaleData} from '@angular/common';
import localeRo from '@angular/common/locales/ro';
import {Component, ContentChild, ContentChildren, Directive, HostBinding, Input, LOCALE_ID, QueryList, TemplateRef, Type, ViewChild, ViewContainerRef, Pipe, PipeTransform} from '@angular/core';
import {setDelayProjection} from '@angular/core/src/render3/instructions/projection';
import {TestBed} from '@angular/core/testing';
import {loadTranslations} from '@angular/localize/run_time';
import {loadTranslations} from '@angular/localize';
import {By} from '@angular/platform-browser';
import {expect} from '@angular/platform-browser/testing/src/matchers';
import {onlyInIvy} from '@angular/private/testing';
@@ -11,7 +11,7 @@ import {Compiler, Component, ComponentFactoryResolver, Directive, DoCheck, Eleme
import {Input} from '@angular/core/src/metadata';
import {ngDevModeResetPerfCounters} from '@angular/core/src/util/ng_dev_mode';
import {TestBed, TestComponentRenderer} from '@angular/core/testing';
import {loadTranslations} from '@angular/localize/run_time';
import {loadTranslations} from '@angular/localize';
import {By, DomSanitizer} from '@angular/platform-browser';
import {expect} from '@angular/platform-browser/testing/src/matchers';
import {ivyEnabled, onlyInIvy} from '@angular/private/testing';
@@ -11,7 +11,8 @@ ng_module(
],
deps = [
"//packages/core",
"//packages/localize/run_time",
"//packages/localize",
"//packages/localize/init",
],
)

@@ -5,8 +5,10 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/

import {loadTranslations} from '@angular/localize/run_time';
// Make the `$localize()` global function available to the compiled templates, and the direct calls
// below. This would normally be done inside the application `polyfills.ts` file.
import '@angular/localize/init';
import {loadTranslations} from '@angular/localize';

const translations = {
'Hello World!': 'Bonjour Monde!',
@@ -17,7 +17,8 @@ ng_module(
"//packages/common",
"//packages/core",
"//packages/core/test/bundling/util:reflect_metadata",
"//packages/localize/run_time",
"//packages/localize",
"//packages/localize/init",
],
)

@@ -6,9 +6,6 @@
* found in the LICENSE file at https://angular.io/license
*/
import '@angular/core/test/bundling/util/src/reflect_metadata';
// Make the `$localize()` global function available to the compiled templates, and the direct calls
// below. This would normally be done inside the application `polyfills.ts` file.
import '@angular/localize';
import './translations';
import {CommonModule} from '@angular/common';
import {Component, Injectable, NgModule, ViewEncapsulation, ɵmarkDirty as markDirty, ɵrenderComponent as renderComponent} from '@angular/core';
@@ -5,10 +5,12 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/

import '@angular/localize/init';
import '@angular/compiler';

importwhenRendered as whenRendered} from '@angular/core';
import {getComponent} from '@angular/core/src/render3';
import {clearTranslations} from '@angular/localize';
import {withBody} from '@angular/private/testing';
import * as path from 'path';

@@ -19,12 +21,7 @@ describe('functional test for todo i18n', () => {
BUNDLES.forEach(bundle => {
describe(bundle, () => {
it('should render todo i18n', withBody('<todo-app></todo-app>', async() => {
// We need to delete the dummy `$localize` that was added because of the import of
// `@angular/core` at the top of this file.
// Also to clear out the translations from the previous test.
// This would not be needed in normal applications since the import of
// `@angular/localize` would be in polyfill.ts before any other import.
($localize as any) = undefined;
clearTranslations();
require(path.join(PACKAGE, bundle));
const toDoAppComponent = getComponent(document.querySelector('todo-app') !);
expect(document.body.textContent).toContain('liste de tâches');
@@ -5,8 +5,10 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/

import {loadTranslations} from '@angular/localize/run_time';
// Make the `$localize()` global function available to the compiled templates, and the direct calls
// below. This would normally be done inside the application `polyfills.ts` file.
import '@angular/localize/init';
import {loadTranslations} from '@angular/localize';

export const translations = {
'What needs to be done?': `Qu'y a-t-il à faire ?`,
@@ -5,7 +5,9 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
import '@angular/localize';
// Make the `$localize()` global function available to the compiled templates, and the direct calls
// below. This would normally be done inside the application `polyfills.ts` file.
import '@angular/localize/init';
import {AfterContentInit, AfterViewInit, Component, ContentChildren, Directive, Input, QueryList, ViewChildren, ɵivyEnabled as ivyEnabled} from '@angular/core';
import {TestBed} from '@angular/core/testing';
import {isCommentNode} from '@angular/platform-browser/testing/src/browser_util';
@@ -12,6 +12,7 @@ ts_library(
),
module_name = "@angular/localize",
deps = [
"//packages/localize/src/localize",
"@npm//@types/node",
],
)
@@ -20,14 +21,14 @@ ng_package(
name = "npm_package",
srcs = [
"package.json",
"//packages/localize/run_time:package.json",
"//packages/localize/init:package.json",
],
entry_point = ":index.ts",
tags = [
"release-with-framework",
],
deps = [
":localize",
"//packages/localize/run_time",
"//packages/localize/init",
],
)
@@ -5,73 +5,9 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
import {_global} from './src/global';
import {$localize as _localize, LocalizeFn, TranslateFn} from './src/localize';

// Attach $localize to the global context, as a side-effect of this module.
_global.$localize = _localize;
// DO NOT ADD public exports to this file.
// The public API exports are specified in the `./localize` module, which is checked by the
// public_api_guard rules

export {LocalizeFn, TranslateFn};

// `declare global` allows us to escape the current module and place types on the global namespace
declare global {
/**
* Tag a template literal string for localization.
*
* For example:
*
* ```ts
* $localize `some string to localize`
* ```
*
* **Naming placeholders**
*
* If the template literal string contains expressions then you can optionally name the
* placeholder
* associated with each expression. Do this by providing the placeholder name wrapped in `:`
* characters directly after the expression. These placeholder names are stripped out of the
* rendered localized string.
*
* For example, to name the `item.length` expression placeholder `itemCount` you write:
*
* ```ts
* $localize `There are ${item.length}:itemCount: items`;
* ```
*
* If you need to use a `:` character directly an expression you must either provide a name or you
* can escape the `:` by preceding it with a backslash:
*
* For example:
*
* ```ts
* $localize `${label}:label:: ${}`
* // or
* $localize `${label}\: ${}`
* ```
*
* **Processing localized strings:**
*
* There are three scenarios:
*
* * **compile-time inlining**: the `$localize` tag is transformed at compile time by a
* transpiler,
* removing the tag and replacing the template literal string with a translated literal string
* from a collection of translations provided to the transpilation tool.
*
* * **run-time evaluation**: the `$localize` tag is a run-time function that replaces and
* reorders
* the parts (static strings and expressions) of the template literal string with strings from a
* collection of translations loaded at run-time.
*
* * **pass-through evaluation**: the `$localize` tag is a run-time function that simply evaluates
* the original template literal string without applying any translations to the parts. This
* version
* is used during development or where there is no need to translate the localized template
* literals.
*
* @param messageParts a collection of the static parts of the template string.
* @param expressions a collection of the values of each placeholder in the template string.
* @returns the translated string, with the `messageParts` and `expressions` interleaved together.
*/
const $localize: LocalizeFn;
}
export * from './localize';
@@ -5,15 +5,15 @@ package(default_visibility = ["//visibility:public"])
exports_files(["package.json"])

ts_library(
name = "run_time",
name = "init",
srcs = glob(
[
"**/*.ts",
],
),
module_name = "@angular/localize/run_time",
module_name = "@angular/localize/init",
deps = [
"//packages/localize",
"//packages/localize/src/localize",
"@npm//@types/node",
],
)
@@ -0,0 +1,76 @@
/**
* @license
* Copyright Google Inc. All Rights Reserved.
*
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
import {$localize, LocalizeFn, _global} from '../src/localize';

export {LocalizeFn, TranslateFn} from '../src/localize';

// Attach $localize to the global context, as a side-effect of this module.
_global.$localize = $localize;

// `declare global` allows us to escape the current module and place types on the global namespace
declare global {
/**
* Tag a template literal string for localization.
*
* For example:
*
* ```ts
* $localize `some string to localize`
* ```
*
* **Naming placeholders**
*
* If the template literal string contains expressions then you can optionally name the
* placeholder
* associated with each expression. Do this by providing the placeholder name wrapped in `:`
* characters directly after the expression. These placeholder names are stripped out of the
* rendered localized string.
*
* For example, to name the `item.length` expression placeholder `itemCount` you write:
*
* ```ts
* $localize `There are ${item.length}:itemCount: items`;
* ```
*
* If you need to use a `:` character directly an expression you must either provide a name or you
* can escape the `:` by preceding it with a backslash:
*
* For example:
*
* ```ts
* $localize `${label}:label:: ${}`
* // or
* $localize `${label}\: ${}`
* ```
*
* **Processing localized strings:**
*
* There are three scenarios:
*
* * **compile-time inlining**: the `$localize` tag is transformed at compile time by a
* transpiler,
* removing the tag and replacing the template literal string with a translated literal string
* from a collection of translations provided to the transpilation tool.
*
* * **run-time evaluation**: the `$localize` tag is a run-time function that replaces and
* reorders
* the parts (static strings and expressions) of the template literal string with strings from a
* collection of translations loaded at run-time.
*
* * **pass-through evaluation**: the `$localize` tag is a run-time function that simply evaluates
* the original template literal string without applying any translations to the parts. This
* version
* is used during development or where there is no need to translate the localized template
* literals.
*
* @param messageParts a collection of the static parts of the template string.
* @param expressions a collection of the values of each placeholder in the template string.
* @returns the translated string, with the `messageParts` and `expressions` interleaved together.
*/
const $localize: LocalizeFn;
}

0 comments on commit 2bf5606

Please sign in to comment.
You can’t perform that action at this time.