mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
Paul Gschwendtner
4c56c45075
This commit addresses two issues: * The init entry-point currenly access code from another entry-point using relative imports, resulting in code to be duplicated. * The init types are now bundled as part of the ng_package APF rule. There is an API extractor bundling issue with global module augmentations. API extractor does not properly handle module augmentation. We need to disable dts bundling for this entry-point to ensure `$localize` remains globally accessible for users. This is an option in the `ng_package` rule. Note that this worked before because `localize/init` was a `ts_library` that did not have its types bundled. As part of this change, the `MessageId` and `TargetMessage` exports are also made public. The localize exported functions rely on these types but they were not exported. Related to types, an exception is added for three private exports from the primary entry-point so that they will show up in the API golden. These private exports are re-exposed publicly in the init entry-point but no golden would capture them due to the private symbol prefix. One might wonder why the symbols are not guarded in the init golden. The reason is that goldens never inline signatures from cross-entry-points/packages to avoid duplication. Lastly, the i18n integration test golden had to be updated because the polyfills bundle increased slightly. After thorough and time-consuming investigation, this mostly happens due to different mangle identifies being used (the input code changed --> so the mangling determinism) Size before this change: ``` SUCCESS: Commit undefined uncompressed runtime did NOT cross size threshold of 500 bytes or >1% (expected: 929, actual: 926). SUCCESS: Commit undefined uncompressed main did NOT cross size threshold of 500 bytes or >1% (expected: 124544, actual: 124660). SUCCESS: Commit undefined uncompressed polyfills did NOT cross size threshold of 500 bytes or >1% (expected: 34530, actual: 34641). ``` After: ``` SUCCESS: Commit undefined uncompressed runtime did NOT cross size threshold of 500 bytes or >1% (expected: 929, actual: 926). SUCCESS: Commit undefined uncompressed main did NOT cross size threshold of 500 bytes or >1% (expected: 124544, actual: 124650). FAIL: Commit undefined uncompressed polyfills exceeded expected size by 500 bytes or >1% (expected: 34530, actual: 35252). ``` Inspecting/comparing without mangling shows that the new changes would actually result in a bundle reduction (potentially visible with gzip/brotli): ``` ➜ Desktop stat -f%z master-nomangle.js 101357 ➜ Desktop stat -f%z with-changes-nomangle.js 101226 ``` PR Close #45405
111 lines
4.2 KiB
TypeScript
111 lines
4.2 KiB
TypeScript
/**
|
|
* @license
|
|
* Copyright Google LLC 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 as $localize, ɵ_global as _global, ɵLocalizeFn as LocalizeFn, ɵTranslateFn as TranslateFn} from '@angular/localize';
|
|
|
|
export {$localize, LocalizeFn, TranslateFn};
|
|
|
|
// 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`
|
|
* ```
|
|
*
|
|
* **Providing meaning, description and id**
|
|
*
|
|
* You can optionally specify one or more of `meaning`, `description` and `id` for a localized
|
|
* string by pre-pending it with a colon delimited block of the form:
|
|
*
|
|
* ```ts
|
|
* $localize`:meaning|description@@id:source message text`;
|
|
*
|
|
* $localize`:meaning|:source message text`;
|
|
* $localize`:description:source message text`;
|
|
* $localize`:@@id:source message text`;
|
|
* ```
|
|
*
|
|
* This format is the same as that used for `i18n` markers in Angular templates. See the
|
|
* [Angular 18n guide](guide/i18n-common-prepare#mark-text-in-component-template).
|
|
*
|
|
* **Naming placeholders**
|
|
*
|
|
* If the template literal string contains expressions, then the expressions will be automatically
|
|
* associated with placeholder names for you.
|
|
*
|
|
* For example:
|
|
*
|
|
* ```ts
|
|
* $localize `Hi ${name}! There are ${items.length} items.`;
|
|
* ```
|
|
*
|
|
* will generate a message-source of `Hi {$PH}! There are {$PH_1} items`.
|
|
*
|
|
* The recommended practice is to name the placeholder associated with each expression though.
|
|
*
|
|
* 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 `items.length` expression placeholder `itemCount` you write:
|
|
*
|
|
* ```ts
|
|
* $localize `There are ${items.length}:itemCount: items`;
|
|
* ```
|
|
*
|
|
* **Escaping colon markers**
|
|
*
|
|
* If you need to use a `:` character directly at the start of a tagged string that has no
|
|
* metadata block, or directly after a substitution expression that has no name you must escape
|
|
* the `:` by preceding it with a backslash:
|
|
*
|
|
* For example:
|
|
*
|
|
* ```ts
|
|
* // message has a metadata block so no need to escape colon
|
|
* $localize `:some description::this message starts with a colon (:)`;
|
|
* // no metadata block so the colon must be escaped
|
|
* $localize `\:this message starts with a colon (:)`;
|
|
* ```
|
|
*
|
|
* ```ts
|
|
* // named substitution so no need to escape colon
|
|
* $localize `${label}:label:: ${}`
|
|
* // anonymous substitution so colon must be escaped
|
|
* $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;
|
|
}
|