Skip to content

Commit

Permalink
docs: add subtopics for internationalization (#43245)
Browse files Browse the repository at this point in the history 
Add subtopics for internationalization guide.

PR Close #43245
  • Loading branch information
@josmar-crwdstffng @alxhub
josmar-crwdstffng authored and alxhub committed Sep 23, 2021
1 parent 579b05a commit 406abf2
Show file tree
Hide file tree
Showing 14 changed files with 37 additions and 236 deletions.
6 changes: 2 additions & 4 deletions aio/content/guide/i18n-common-add-package.md
View file
Expand Up @@ -5,9 +5,7 @@

To take advantage of the localization features of Angular, use the Angular CLI to add the `@angular/localize` package to your project.

<code-example language="sh">
ng add @angular/localize
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="add-localize" language="sh"></code-example>

This command updates the `package.json` and `polyfills.ts` files of your project to import the `@angular/localize` package.

Expand All @@ -27,4 +25,4 @@ If `@angular/localize` is not installed, the Angular CLI may generate an error w

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
85 changes: 4 additions & 81 deletions aio/content/guide/i18n-common-deploy.md
View file
Expand Up @@ -10,27 +10,7 @@ To adjust the base `href` for each version of the application, the CLI adds the
Specify the `"baseHref"` for each locale in your workspace configuration file (`angular.json`).
The following example displays `"baseHref"` set to an empty string.

<code-example language="json" header="angular.json">
...
"projects": {
"angular.io-example": {
...
"i18n": {
"sourceLocale": "en-US",
"locales": {
"fr": {
"translation": "src/locale/messages.fr.xlf",
"baseHref": ""
}
}
},
"architect": {
...
}
...
}
}
</code-example>
<code-example language="json" header="angular.json" path="i18n/angular.json" region="i18n-baseHref" ></code-example>

Also, to declare the base `href` at compile time, use the CLI `--baseHref` option with [`ng build`][AioCliBuild].

Expand All @@ -48,70 +28,13 @@ For more information on how to deploy apps to a remote server, see [Deployment][

The following example displays an Nginx configuration.

```nginx
http {
# Browser preferred language detection (does NOT require
# AcceptLanguageModule)
map $http_accept_language $accept_language {
~*^de de;
~*^fr fr;
~*^en en;
}
# ...
}
server {
listen 80;
server_name localhost;
root /www/data;
# Fallback to default language if no preference defined by browser
if ($accept_language ~ "^$") {
set $accept_language "fr";
}
# Redirect "/" to Angular application in the preferred language of the browser
rewrite ^/$ /$accept_language permanent;
# Everything under the Angular application is always redirected to Angular in the
# correct language
location ~ ^/(fr|de|en) {
try_files $uri /$1/index.html?$args;
}
# ...
}
```
<code-example path="i18n/doc-files/nginx.conf" language="nginx"></code-example>

#### Apache

The following example displays an Apache configuration.

```apache
<VirtualHost *:80>
ServerName localhost
DocumentRoot /www/data
<Directory "/www/data">
RewriteEngine on
RewriteBase /
RewriteRule ^../index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (..) $1/index.html [L]
RewriteCond %{HTTP:Accept-Language} ^de [NC]
RewriteRule ^$ /de/ [R]
RewriteCond %{HTTP:Accept-Language} ^en [NC]
RewriteRule ^$ /en/ [R]
RewriteCond %{HTTP:Accept-Language} !^en [NC]
RewriteCond %{HTTP:Accept-Language} !^de [NC]
RewriteRule ^$ /fr/ [R]
</Directory>
</VirtualHost>
```
<code-example path="i18n/doc-files/apache2.conf" language="apache"></code-example>

<!-- links -->

Expand All @@ -123,4 +46,4 @@ The following example displays an Apache configuration.

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
2 changes: 1 addition & 1 deletion aio/content/guide/i18n-common-format-data-locale.md
View file
Expand Up @@ -28,4 +28,4 @@ For example, to force the currency to use `en-US` no matter which language-local

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
2 changes: 1 addition & 1 deletion aio/content/guide/i18n-common-locale-id.md
View file
Expand Up @@ -52,4 +52,4 @@ The build process (described in [Merge translations into the app][AioGuideI18nCo

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
107 changes: 10 additions & 97 deletions aio/content/guide/i18n-common-merge.md
View file
Expand Up @@ -54,24 +54,7 @@ The following sub-options identify the source language and tell the compiler whe

For example, the following excerpt of an `angular.json` file sets the source locale to `en-US` and provides the path to the `fr` (French) locale translation file:

<code-example language="json" header="angular.json">
...
"projects": {
"my-project": {
...
"i18n": {
"sourceLocale": "en-US",
"locales": {
"fr": "src/locale/messages.fr.xlf"
}
},
"architect": {
...
},
...
}
}
</code-example>
<code-example language="json" header="angular.json" path="i18n/angular.json" region="locale-config"></code-example>

### Generate application versions for each locale

Expand All @@ -93,17 +76,7 @@ If you changed this setting, set `"aot"` to `true` in order to use AOT.

The following example displays the `"localize"` option set to `true` in `angular.json`, so that all locales defined in the build configuration are built.

<code-example language="json" header="angular.json">
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": {
"localize": true,
"aot": true,
...
}
...
}
</code-example>
<code-example language="json" header="angular.json" path="i18n/angular.json" region="build-localize-true"></code-example>

<div class="alert is-helpful">

Expand All @@ -130,9 +103,7 @@ The CLI builds all locales defined in the build configuration.
If you set the locales in build configuration, it is similar to when you set the `"localize"` option to `true`.
For more information about how to set the locales, see [Generate application versions for each locale][AioGuideI18nCommonMergeGenerateApplicationVersionsForEachLocale].

<code-example language="sh">
ng build --localize
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="build-localize" language="sh"></code-example>

### Apply specific build options for just one locale

Expand All @@ -141,35 +112,12 @@ ng build --localize
To apply specific build options to only one locale, specify a single locale to create a custom locale-specific configuration.
The following example displays a custom locale-specific configuration using a single locale.

<code-example language="json" header="angular.json">
"build": {
...
"configurations": {
...
"fr": {
"localize": ["fr"],
"main": "src/main.fr.ts",
...
}
}
},
"serve": {
...
"configurations": {
...
"fr": {
"browserTarget": "*project-name*:build:fr"
}
}
}
</code-example>
<code-example language="json" header="angular.json" path="i18n/angular.json" region="build-single-locale"></code-example>

Pass this configuration to the `ng serve` or `ng build` commands.
The following code example displays how to serve the French language file.

<code-example language="sh">
ng serve --configuration=fr
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="serve-french" language="sh"></code-example>

<div class="alert is-important">

Expand All @@ -179,39 +127,9 @@ Use the CLI development server (`ng serve`) with only a single locale.

For production builds, use configuration composition to run both configurations.

<code-example language="sh">
ng build --configuration=production,fr
</code-example>

<code-example language="json" header="angular.json">
...
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": { ... },
"configurations": {
"fr": {
"localize": ["fr"],
}
}
},
...
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"browserTarget": "my-project:build"
},
"configurations": {
"production": {
"browserTarget": "my-project:build:production"
},
"fr": {
"browserTarget": "my-project:build:fr"
}
}
}
}
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="build-production-french" language="sh"></code-example>

<code-example language="json" header="angular.json" path="i18n/angular.json" region="build-production-french" ></code-example>

### Report missing translations

Expand All @@ -229,12 +147,7 @@ To configure the level of warning that is generated by the Angular compiler, spe
Specify the warning level in the `options` section for the `build` target of your Angular CLI configuration file (`angular.json`).
The following example displays how to set the warning level to `error`.

<code-example language="json" header="angular.json">
"options": {
...
"i18nMissingTranslation": "error"
}
</code-example>
<code-example language="json" header="angular.json" path="i18n/angular.json" region="missing-translation-error" ></code-example>

<!-- links -->

Expand All @@ -261,4 +174,4 @@ The following example displays how to set the warning level to `error`.

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
10 changes: 2 additions & 8 deletions aio/content/guide/i18n-common-prepare.md
View file
Expand Up @@ -160,13 +160,7 @@ Many locales don't support some of the pluralization categories.
For example, the default locale (`en-US`) and other locales (such as `es`) have very simple `plural()` functions that don't support the `few` category.
The following code example displays the [en-US][GithubAngularAngularBlobEcffc3557fe1bff9718c01277498e877ca44588dPackagesCoreSrcI18nLocaleEnTsL15L18] `plural()` function.

```typescript
function plural(n: number): number {
let i = Math.floor(Math.abs(n)), v = n.toString().replace(/^[^.]*\.?/, '').length;
if (i === 1 && v === 0) return 1;
return 5;
}
```
<code-example path="i18n/doc-files/locale_plural_function.ts" class="no-box" hideCopy></code-example>

The function will only ever return 1 (`one`) or 5 (`other`).
The `few` category will never match.
Expand Down Expand Up @@ -217,4 +211,4 @@ The following example displays nested clauses.

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
22 changes: 5 additions & 17 deletions aio/content/guide/i18n-common-translation-files.md
View file
Expand Up @@ -21,9 +21,7 @@ Follow these steps:

To extract the source language file, open a terminal window, change to the root directory of your application project, and run the following CLI command:

<code-example language="sh">
ng extract-i18n
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="extract-i18n-default" language="sh"></code-example>

The `extract-i18n` command creates a source language file named `messages.xlf` in the root directory of your project using the [XML Localization Interchange File Format (XLIFF, version 1.2)][WikipediaWikiXliff].

Expand All @@ -45,9 +43,7 @@ Angular 9 uses the source locale configured in the [workspace configuration][Aio
To create a file in the `src/locale` directory, specify the output path as an option.
The following example specifies the output path as an option.

<code-example language="sh">
ng extract-i18n --output-path src/locale
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="extract-i18n-output-path" language="sh"></code-example>

#### Change the source language file format

Expand All @@ -64,13 +60,7 @@ The `extract-i18n` command writes files in the following translation formats.
Specify the translation format explicitly with the `--format` command option.
The following example demonstrates several translation formats.

<code-example language="sh">
ng extract-i18n --format=xlf
ng extract-i18n --format=xlf2
ng extract-i18n --format=xmb
ng extract-i18n --format=json
ng extract-i18n --format=arb
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="extract-i18n-formats" language="sh"></code-example>

<div class="alert is-helpful">

Expand All @@ -84,9 +74,7 @@ The XMB format generates `.xmb` source language files but uses`.xtb` (XML Transl
To change the name of the source language file generated by the extraction tool, use
the `--outFile` command option:

<code-example language="sh">
ng extract-i18n --out-file source.xlf
</code-example>
<code-example path="i18n/doc-files/commands.sh" region="extract-i18n-out-file" language="sh"></code-example>

### Create a translation file for each language

Expand Down Expand Up @@ -245,4 +233,4 @@ The following example displays both translation units after translating.

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
2 changes: 1 addition & 1 deletion aio/content/guide/i18n-common.md
View file
Expand Up @@ -78,4 +78,4 @@ In special cases, the following actions are required.

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
2 changes: 1 addition & 1 deletion aio/content/guide/i18n-example.md
View file
Expand Up @@ -23,4 +23,4 @@ The following tabs display the example application and the associated translatio

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15
6 changes: 2 additions & 4 deletions aio/content/guide/i18n-optional-import-global-variants.md
View file
Expand Up @@ -10,9 +10,7 @@ Global variants of the locale data are available in [`@angular/common/locales/gl

The following example imports the global variants for French (`fr`).

<code-example language="javascript" header="app.module.ts">
import '@angular/common/locales/global/fr';
</code-example>
<code-example path="i18n/doc-files/app.module.ts" header="src/app/app.module.ts" region="global-locale"></code-example>

<!-- links -->

Expand All @@ -25,4 +23,4 @@ import '@angular/common/locales/global/fr';

<!-- end links -->

@reviewed 2021-08-23
@reviewed 2021-09-15

0 comments on commit 406abf2

Please sign in to comment.