diff --git a/aio/content/guide/angular-compiler-options.md b/aio/content/guide/angular-compiler-options.md index 1578b5e5c9c..beab70fcf5f 100644 --- a/aio/content/guide/angular-compiler-options.md +++ b/aio/content/guide/angular-compiler-options.md @@ -1,6 +1,6 @@ # Angular compiler options -When you use [AOT compilation](guide/aot-compiler), you can control how your application is compiled by specifying *template* compiler options in the [TypeScript configuration file](guide/typescript-configuration). +When you use [ahead-of-time compilation (AOT)](guide/aot-compiler), you can control how your application is compiled by specifying *template* compiler options in the [TypeScript configuration file](guide/typescript-configuration). The template options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler. @@ -28,7 +28,7 @@ The following options are available for configuring the AOT template compiler. ### `allowEmptyCodegenFiles` -When `true`, generate all possible files even if they are empty. +When `true`, create all possible files even if they are empty. Default is `false`. Used by the Bazel build rules to simplify how Bazel rules track file dependencies. Do not use this option outside of the Bazel rules. @@ -37,7 +37,7 @@ Do not use this option outside of the Bazel rules. Modifies how Angular-specific annotations are emitted to improve tree-shaking. Non-Angular annotations are not affected. -One of `static fields` \(the default\) or `decorators`. +One of `static fields` or `decorators`. The default value is `static fields`. * By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like [Closure compiler](https://github.com/google/closure-compiler) to remove unused classes * The `decorators` value leaves the decorators in place, which makes compilation faster. @@ -53,9 +53,13 @@ One of `static fields` \(the default\) or `decorators`. ### `annotateForClosureCompiler` + + When `true`, use [Tsickle](https://github.com/angular/tsickle) to annotate the emitted JavaScript with [JSDoc](https://jsdoc.app) comments needed by the [Closure Compiler](https://github.com/google/closure-compiler). Default is `false`. + + ### `compilationMode` Specifies the compilation mode to use. @@ -70,29 +74,29 @@ The default value is `'full'`. ### `disableExpressionLowering` -When `true` \(the default\), transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. +When `true`, the default, transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. See [metadata rewriting](guide/aot-compiler#metadata-rewriting) for more information. When `false`, disables this rewriting, requiring the rewriting to be done manually. ### `disableTypeScriptVersionCheck` -When `true`, the compiler does not check the TypeScript version and does not report an error when an unsupported version of TypeScript is used. +When `true`, the compiler does not look at the TypeScript version and does not report an error when an unsupported version of TypeScript is used. Not recommended, as unsupported versions of TypeScript might have undefined behavior. Default is `false`. ### `enableI18nLegacyMessageIdFormat` -Instructs the Angular template compiler to generate legacy ids for messages that are tagged in templates by the `i18n` attribute. +Instructs the Angular template compiler to create legacy ids for messages that are tagged in templates by the `i18n` attribute. See [Mark text for translations][AioGuideI18nCommonPrepareMarkTextInComponentTemplate] for more information about marking messages for localization. -Set this option to `false` unless your project relies upon translations that were previously generated using legacy IDs. +Set this option to `false` unless your project relies upon translations that were created earlier using legacy IDs. Default is `true`. -The pre-Ivy message extraction tooling generated a variety of legacy formats for extracted message IDs. -These message formats have a number of issues, such as whitespace handling and reliance upon information inside the original HTML of a template. +The pre-Ivy message extraction tooling created a variety of legacy formats for extracted message IDs. +These message formats have some issues, such as whitespace handling and reliance upon information inside the original HTML of a template. -The new message format is more resilient to whitespace changes, is the same across all translation file formats, and can be generated directly from calls to `$localize`. +The new message format is more resilient to whitespace changes, is the same across all translation file formats, and can be created directly from calls to `$localize`. This allows `$localize` messages in application code to use the same ID as identical `i18n` messages in component templates. ### `enableResourceInlining` @@ -101,30 +105,30 @@ When `true`, replaces the `templateUrl` and `styleUrls` properties in all `@Comp When enabled, the `.js` output of `ngc` does not include any lazy-loaded template or style URLs. -For library projects generated with the Angular CLI, the development configuration default is `true`. +For library projects created with the Angular CLI, the development configuration default is `true`. ### `enableLegacyTemplate` -When `true`, enables use of the `