diff --git a/aio/content/guide/i18n.md b/aio/content/guide/i18n.md index cb94b29b3c4..76e49a520f5 100644 --- a/aio/content/guide/i18n.md +++ b/aio/content/guide/i18n.md @@ -57,9 +57,9 @@ To localize your application, complete the following general actions. 6. [Merge translations into the app][AioGuideI18nMerge]. 7. [Deploy multiple locales][AioGuideI18nDeployLocales]. -While you follow the actions, [explore the translated example app][AioGuideI18nAppPreTranslation]. +While following these steps, [explore the translated example app](#app-pre-translation). -In special cases, the following actions are required. +The following are optional practices that might be required in special cases: * [Set the source locale manually][AioGuideI18nSetSourceManually], if you need to set the [LOCALE_ID][AioApiCoreLocaleId] token. * [Import global variants of the locale data][AioGuideI18nImportLocale] for extra locale data. @@ -84,9 +84,7 @@ For more information about `package.json` and polyfill packages, see [Workspace -If `@angular/localize` is not installed, the Angular CLI may generate an error when you try to build a localized version of your application. - - +If `@angular/localize` is not installed, the Angular CLI might generate an error when you try to build a localized version of your app. {@a setting-up-locale} {@a setting-up-the-locale-of-your-app} @@ -186,17 +184,16 @@ It is not an Angular directive. ### Add helpful descriptions and meanings -To translate a text message accurately, the translator may need additional information or context. -Add a *description* of the text message as the value of the `i18n` attribute. -The following example displays the value of the `i18n` attribute. +To translate a text message accurately, the translator might need additional information or context. +Add a _description_ of the text message as the value of the `i18n` attribute, as shown in the following example: -The translator may also need to know the meaning or intent of the text message within this particular application context, in order to translate it the same way as other text with the same meaning. -Start the `i18n` attribute value with the *meaning* and separate it from the *description* with the `|` character: `|`. +The translator might also need to know the meaning or intent of the text message within this particular app context, in order to translate it the same way as other text with the same meaning. +Start the `i18n` attribute value with the _meaning_ and +separate it from the _description_ with the `|` character: `|`. -For example, you may want to indicate that the `

` tag is a site header that needs to be translated the same way whether it used as a header or referenced in another section of text. -The following example displays how to indicate that the `

` tag needs to be translated as a header or referenced elsewhere. +For example, to add the meaning that this `

` tag is a site header that needs to be translated the same way, not only when used as a header, but also when referred to from another section of text: @@ -280,9 +277,10 @@ The ICU clauses adhere to the [ICU Message Format][GithubUnicodeOrgIcuUserguideF #### Mark plurals -Use the `plural` clause to mark expressions that may not be meaningful if translated word-for-word. +Use the `plural` clause to mark expressions that might not be meaningful if translated word-for-word. + +For example, if you want to display "updated x minutes ago" in English, you might want to display "just now", "one minute ago", or "_x_ minutes ago" (with _x_ as the actual number). -For example, if you want to display "updated x minutes ago" in English, you may want to display "just now", "one minute ago", or "*x* minutes ago" (with *x* as the actual number). Other languages might express this cardinality differently. The following example displays how to use a `plural` clause to express each of the three situations. @@ -310,7 +308,7 @@ Pluralization categories include (depending on the language): * `other`
-
Locales may not support some pluralization categories
+
Locales might not support some pluralization categories
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. @@ -450,9 +448,7 @@ For example, to create a French translation file, follow these steps: 3. Rename the copy to `messages.fr.xlf` for the French language (`fr`) translation. Send this translation file to the translator. -Repeat the above steps for each language you want to add to your application. - - +Repeat the preceding steps for each language you want to add to your app. {@a translate-text-nodes} @@ -662,9 +658,8 @@ The following example displays the `"localize"` option set to `true` in `angular
Due to the deployment complexities of i18n and the need to minimize rebuild time, the development server only supports localizing a single locale at a time. -If you set the `"localize"` option to `true`, define more than one locale, and use `ng serve`; then an error occurs. -If you want to develop against a specific locale, set the `"localize"` option to a specific locale. -For example, for French (`fr`), specify `"localize": ["fr"]`. +Setting the `"localize"` option to `true` causes an error when using `ng serve` if more than one locale is defined. +Setting the option to a specific locale, such as `"localize": ["fr"]`, can work if you want to develop against a specific locale (such as `fr`).
@@ -672,18 +667,14 @@ The CLI loads and registers the locale data, places each generated version in a For each application variant the `lang` attribute of the `html` element is set to the locale. The CLI also adjusts the HTML base HREF for each version of the application by adding the locale to the configured `baseHref`. -Set the `"localize"` property as a shared configuration to effectively inherit for all the configurations. -Also, set the property to override other configurations. - - +Set the `"localize"` property as a shared configuration that all the configurations effectively inherit (or can override). {@a localize-build-command} ### Build from the command line -Also, use the `--localize` option with the [`ng build`][AioCliBuild] command and your existing `production` configuration. -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`. +Use the `--localize` option with the [`ng build`][AioCliBuild] command and your existing `production` configuration. +The CLI builds all locales defined in the build configuration, which is similar to setting the `"localize"` option to `true` as described in the previous section. For more information about how to set the locales, see [Generate application versions for each locale][AioGuideI18nLocalizeGenerate]. @@ -694,8 +685,7 @@ For more information about how to set the locales, see [Generate application ver ### Apply specific build options for just one locale -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. +To apply specific build options to only one locale, create a custom locale-specific configuration by specifying a single locale as shown in the following example: @@ -710,7 +700,7 @@ Use the CLI development server (`ng serve`) with only a single locale.
-For production builds, use configuration composition to run both configurations. +For production builds, use configuration composition to execute both configurations: @@ -744,11 +734,7 @@ The following example displays how to set the warning level to `error`. If `myapp` is the directory containing the distributable files of your application, you would typically make available different versions for different locales in locale directories such as `myapp/fr` for the French version and `myapp/es` for the Spanish version. -The HTML `base` tag with the `href` attribute specifies the base URI, or URL, for relative links. -If you set the `"localize"` option in `angular.json` to `true` or to an array of locale IDs, the CLI adjusts the base `href` for each version of the application. -To adjust the base `href` for each version of the application, the CLI adds the locale to the configured `"baseHref"`. -Specify the `"baseHref"` for each locale in your workspace configuration file (`angular.json`). -The following example displays `"baseHref"` set to an empty string. +The HTML `base` tag with the `href` attribute specifies the base URI, or URL, for relative links. If you set the `"localize"` option in `angular.json` to `true` or to an array of locale IDs, the CLI adjusts the base `href` for each version of the app by adding the locale to the configured `"baseHref"`. Specify the `"baseHref"` for each locale in your workspace configuration file (`angular.json`), as shown in the following example, which sets `"baseHref"` to an empty string: @@ -829,7 +815,7 @@ The following example sets the value of `LOCALE_ID` to `fr` for French. ### Import global variants of the locale data -Angular will automatically include locale data if you configure the locale using the `--localize` option with [`ng build`][AioCliBuild] CLI command. +Angular automatically includes locale data if you configure the locale using the `--localize` option with [`ng build`](cli/build "ng build description") CLI command. The [Angular repository][GithubAngularAngularTreeMasterPackagesCommonLocales] files (`@angular/common/locales`) contain most of the locale data that you need, but some advanced formatting options require additional locale data. @@ -856,11 +842,12 @@ In most cases a text change would also require a change to the translation. Therefore, using a new ID keeps the text change in sync with translations. However, some translation systems require a specific form or syntax for the ID. -To address this requirement, mark text with custom IDs. -While most developers don't need to use custom IDs, some may want to use IDs that have a unique syntax to convey additional metadata (such as the library, component, or area of the application in which the text appears). -Specify a custom ID in the `i18n` attribute by using the `@@` prefix. -The following example defines the `introductionHeader` custom ID. +To address this requirement, you can mark text with _custom_ IDs. +While most developers don't need to use custom IDs, some might want to use IDs that have a unique syntax to convey additional metadata (such as the library, component, or area of the app in which the text appears). + +To specify a custom ID in the `i18n` attribute using the prefix `@@`. +The following example defines the custom ID `introductionHeader`: @@ -870,7 +857,7 @@ When you specify a custom ID, the extractor generates a translation unit with th If you change the text, the extractor does *not* change the ID. As a result, you don't have to take the extra step of updating the translation. -The drawback of using custom IDs is that if you change the text, your translation may be out-of-sync with the newly changed source text. +The drawback of using custom IDs is that if you change the text, your translation might be out-of-sync with the newly changed source text. #### Use a custom ID with a description diff --git a/aio/content/guide/testing-attribute-directives.md b/aio/content/guide/testing-attribute-directives.md index 35b0b48683f..5d4e11aa026 100644 --- a/aio/content/guide/testing-attribute-directives.md +++ b/aio/content/guide/testing-attribute-directives.md @@ -8,9 +8,9 @@ Its name reflects the way the directive is applied: as an attribute on a host el
- For a hands-on experience you can run tests and explore the test code in your browser as your read this guide. + For a hands-on experience, run tests and explore the test code in your browser as your read this guide. - If you'd like to experiment with the application that this guide describes, you can run it in your browser or download and run it locally. + If you'd like to experiment with the application that this guide describes, run it in your browser or download and run it locally.
diff --git a/aio/content/guide/testing-pipes.md b/aio/content/guide/testing-pipes.md index 5cb734e2e02..8ed62629b43 100644 --- a/aio/content/guide/testing-pipes.md +++ b/aio/content/guide/testing-pipes.md @@ -4,9 +4,9 @@ You can test [pipes](guide/pipes) without the Angular testing utilities.
- For a hands-on experience you can run tests and explore the test code in your browser as your read this guide. + For a hands-on experience, run tests and explore the test code in your browser as you read this guide. - If you'd like to experiment with the application that this guide describes, you can run it in your browser or download and run it locally. + If you'd like to experiment with the application that this guide describes, run it in your browser or download and run it locally.
diff --git a/aio/content/guide/testing-utility-apis.md b/aio/content/guide/testing-utility-apis.md index 286804ecb05..5b18813764d 100644 --- a/aio/content/guide/testing-utility-apis.md +++ b/aio/content/guide/testing-utility-apis.md @@ -336,8 +336,8 @@ Here are the most important static methods, in order of likely utility. The testing shims (`karma-test-shim`, `browser-test-shim`) call it for you so there is rarely a reason for you to call it yourself. - You may call this method _exactly once_. If you must change - this default in the middle of your test run, call `resetTestEnvironment` first. + Call this method _exactly once_. To change + this default in the middle of a test run, call `resetTestEnvironment` first. Specify the Angular compiler factory, a `PlatformRef`, and a default Angular testing module. Alternatives for non-browser platforms are available in the general form