docs: rename ng xi18n to ng extract-i18n (#39337)
In Angular CLI version 11, xi18n has been changed from `ng xi18n` to `ng extract-i18n`. PR Close #39337
This commit is contained in:
Alan Agius
Joey Perrott
parent
e3d2f46bbd
commit
dd0ba3f4ab
@ -327,7 +327,7 @@ You can also nest different clauses together, such as the `plural` and `select`
|
||||
|
||||
## Work with translation files
|
||||
|
||||
After preparing a template for translation, use the Angular CLI `xi18n` command to extract the marked text in the template into a _source language_ file.
|
||||
After preparing a template for translation, use the Angular CLI `extract-i18n` command to extract the marked text in the template into a _source language_ file.
|
||||
The marked text includes text marked with `i18n` and attributes marked with `i18n-`*attribute* as described in the previous section.
|
||||
Follow these steps:
|
||||
|
||||
@ -344,12 +344,12 @@ You can optionally change the location, format, and name.
|
||||
To extract the source language file, open a terminal window, change to the root directory of your app project, and run the following CLI command:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng xi18n
|
||||
ng extract-i18n
|
||||
</code-example>
|
||||
|
||||
The `xi18n` command creates a source language file named `messages.xlf` in your project's root directory using the [XML Localization Interchange File Format (XLIFF, version 1.2)](https://en.wikipedia.org/wiki/XLIFF "Wikipedia page about XLIFF").
|
||||
The `extract-i18n` command creates a source language file named `messages.xlf` in your project's root directory using the [XML Localization Interchange File Format (XLIFF, version 1.2)](https://en.wikipedia.org/wiki/XLIFF "Wikipedia page about XLIFF").
|
||||
|
||||
Use the following `xi18n` command options to change the source language file location, format, and file name:
|
||||
Use the following `extract-i18n` command options to change the source language file location, format, and file name:
|
||||
|
||||
* `--output-path`: Change the location.
|
||||
* `--format`: Change the format.
|
||||
@ -358,25 +358,19 @@ Use the following `xi18n` command options to change the source language file loc
|
||||
Note: The `--i18n-locale` option is deprecated.
|
||||
Angular 9 uses the source locale configured in your app's [workspace configuration](guide/workspace-config "Angular workspace configuration") file (`angular.json`).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
The ng xi18n extraction mechanism uses the ViewEngine compiler, which is not able to cope with some code syntax that the Ivy compiler can handle. A fix for this issue is currently under development. To follow or contribute to this fix see [PR 32912](https://github.com/angular/angular/pull/32912).
|
||||
|
||||
</div>
|
||||
|
||||
#### Change the source language file location
|
||||
|
||||
To create a file in the `src/locale` directory, specify the output path as an option, as shown in the following example:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng xi18n --output-path src/locale
|
||||
ng extract-i18n --output-path src/locale
|
||||
</code-example>
|
||||
|
||||
{@a other-formats}
|
||||
|
||||
#### Change the source language file format
|
||||
|
||||
The `xi18n` command can read and write files in three translation formats:
|
||||
The `extract-i18n` command can read and write files in three translation formats:
|
||||
|
||||
* XLIFF 1.2 (default)
|
||||
* XLIFF 2
|
||||
@ -385,9 +379,9 @@ The `xi18n` command can read and write files in three translation formats:
|
||||
Specify the translation format explicitly with the `--format` command option, as shown in the following examples:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng xi18n --format=xlf
|
||||
ng xi18n --format=xlf2
|
||||
ng xi18n --format=xmb
|
||||
ng extract-i18n --format=xlf
|
||||
ng extract-i18n --format=xlf2
|
||||
ng extract-i18n --format=xmb
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-helpful">
|
||||
@ -403,14 +397,14 @@ To change the name of the source language file generated by the extraction tool,
|
||||
the `--outFile` command option:
|
||||
|
||||
<code-example language="sh" class="code-shell">
|
||||
ng xi18n --out-file source.xlf
|
||||
ng extract-i18n --out-file source.xlf
|
||||
</code-example>
|
||||
|
||||
{@a localization-folder}
|
||||
|
||||
### Create a translation file for each language
|
||||
|
||||
The `ng xi18n` command (with no options) generates a source language file named `messages.xlf` in the project `src` folder.
|
||||
The `ng extract-i18n` command (with no options) generates a source language file named `messages.xlf` in the project `src` folder.
|
||||
Create *translation* files for each language by copying the source language file.
|
||||
To avoid confusion with multiple translations, you should organize the language translation files by locale in a dedicated `locale` folder under `src/`.
|
||||
Use a filename extension that matches the associated locale, such as `messages.fr.xlf`.
|
||||
|
||||
@ -149,7 +149,7 @@ See [Build target](#build-target) below for more information.
|
||||
|
||||
* The `architect/lint` section configures defaults for options of the `ng lint` command, which performs code analysis on project source files. The default linting tool for Angular is [TSLint](https://palantir.github.io/tslint/).
|
||||
|
||||
* The `architect/extract-i18n` section configures defaults for options of the `ng-xi18n` tool used by the `ng xi18n` command, which extracts marked message strings from source code and outputs translation files.
|
||||
* The `architect/extract-i18n` section configures defaults for options of the `ng extract-i18n` command, which extracts marked message strings from source code and outputs translation files.
|
||||
|
||||
* The `architect/server` section configures defaults for creating a Universal app with server-side rendering, using the `ng run <project>:server` command.
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
"test": "ng test",
|
||||
"lint": "ng lint",
|
||||
"e2e": "ng e2e",
|
||||
"extract": "ng xi18n --output-path=locale"
|
||||
"extract": "ng extract-i18n --output-path=locale"
|
||||
},
|
||||
"private": true,
|
||||
"dependencies": {
|
||||
|
||||
@ -20,7 +20,7 @@ These translated apps are stored in `tmp/translations/(de|fr)`.
|
||||
|
||||
### legacy
|
||||
|
||||
The legacy `ng xi18n` tool extracts the messages from the Angular templates, into the XLIFF 1.2
|
||||
The CLI `ng extract-i18n` tool extracts the messages from the Angular templates, into the XLIFF 1.2
|
||||
format with legacy message ids (`tmp/legacy-locales/messages.legacy.xlf`).
|
||||
|
||||
The translation file is modified to apply a simple translation.
|
||||
|
||||
@ -41,7 +41,7 @@ const extract = (from: string, regex: any, transformFn: (match: any[], state: Se
|
||||
};
|
||||
|
||||
// verify that we extracted all the necessary translations
|
||||
// and their ids match the ones extracted via 'ng xi18n'
|
||||
// and their ids match the ones extracted via 'ng extract-i18n'
|
||||
const verifyTranslationIds =
|
||||
(source: string, output: string, exceptions = {},
|
||||
interpolationConfig: InterpolationConfig = DEFAULT_INTERPOLATION_CONFIG) => {
|
||||
@ -2982,7 +2982,8 @@ describe('i18n support in the template compiler', () => {
|
||||
`;
|
||||
|
||||
const exceptions = {
|
||||
'3052001905251380936': 'Wrapper message generated by "ng xi18n" around ICU: " {$ICU} "'
|
||||
'3052001905251380936':
|
||||
'Wrapper message generated by "ng extract-i18n" around ICU: " {$ICU} "'
|
||||
};
|
||||
verify(input, output, {exceptions});
|
||||
});
|
||||
|
||||
@ -2064,7 +2064,7 @@ export function parseTemplate(
|
||||
|
||||
// process i18n meta information (scan attributes, generate ids)
|
||||
// before we run whitespace removal process, because existing i18n
|
||||
// extraction process (ng xi18n) relies on a raw content to generate
|
||||
// extraction process (ng extract-i18n) relies on a raw content to generate
|
||||
// message ids
|
||||
const i18nMetaVisitor = new I18nMetaVisitor(
|
||||
interpolationConfig, /* keepI18nAttrs */ !preserveWhitespaces,
|
||||
@ -2077,7 +2077,7 @@ export function parseTemplate(
|
||||
// run i18n meta visitor again in case whitespaces are removed (because that might affect
|
||||
// generated i18n message content) and first pass indicated that i18n content is present in a
|
||||
// template. During this pass i18n IDs generated at the first pass will be preserved, so we can
|
||||
// mimic existing extraction process (ng xi18n)
|
||||
// mimic existing extraction process (ng extract-i18n)
|
||||
if (i18nMetaVisitor.hasI18nMeta) {
|
||||
rootNodes = html.visitAll(
|
||||
new I18nMetaVisitor(interpolationConfig, /* keepI18nAttrs */ false), rootNodes);
|
||||
|
||||
@ -1260,7 +1260,7 @@ Resulting in same string which Angular can process:
|
||||
|
||||
### Placeholders with multiple values
|
||||
|
||||
While extracting messages via `ng xi18n`, the tool performs an optimization and reuses the same placeholders for elements/interpolations in case placeholder content is identical.
|
||||
While extracting messages via `ng extract-i18n`, the tool performs an optimization and reuses the same placeholders for elements/interpolations in case placeholder content is identical.
|
||||
For example the following template:
|
||||
```html
|
||||
<b>My text 1</b><b>My text 2</b>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user