translate: translation for configuration guides

adev-es/src/content/reference/configs/angular-compiler-options.en.md

@@ -0,0 +1,234 @@
+# Angular compiler options
+
+When you use [ahead-of-time compilation (AOT)](tools/cli/aot-compiler), you can control how your application is compiled by specifying Angular compiler options in the [TypeScript configuration file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+
+The Angular options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler.
+
+<docs-code header="tsconfig.json" path="adev/src/content/examples/angular-compiler-options/tsconfig.json" visibleRegion="angular-compiler-options"/>
+
+## Configuration inheritance with `extends`
+
+Like the TypeScript compiler, the Angular AOT compiler also supports `extends` in the `angularCompilerOptions` section of the TypeScript configuration file.
+The `extends` property is at the top level, parallel to `compilerOptions` and `angularCompilerOptions`.
+
+A TypeScript configuration can inherit settings from another file using the `extends` property.
+The configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file.
+
+For example:
+
+<docs-code header="tsconfig.app.json" path="adev/src/content/examples/angular-compiler-options/tsconfig.app.json" visibleRegion="angular-compiler-options-app"/>
+
+For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+
+## Template options
+
+The following options are available for configuring the Angular AOT compiler.
+
+### `annotationsAs`
+
+Modifies how Angular-specific annotations are emitted to improve tree-shaking.
+Non-Angular annotations are not affected.
+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.
+  TypeScript emits calls to the `__decorate` helper.
+  Use `--emitDecoratorMetadata` for runtime reflection.
+
+  HELPFUL: That the resulting code cannot tree-shake properly.
+
+### `annotateForClosureCompiler`
+
+<!-- vale Angular.Angular_Spelling = NO -->
+
+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`.
+
+<!-- vale Angular.Angular_Spelling = YES -->
+
+### `compilationMode`
+
+Specifies the compilation mode to use.
+The following modes are available:
+
+| Modes       | Details                                                                                             |
+| :---------- | :-------------------------------------------------------------------------------------------------- |
+| `'full'`    | Generates fully AOT-compiled code according to the version of Angular that is currently being used. |
+| `'partial'` | Generates code in a stable, but intermediate form suitable for a published library.                 |
+
+The default value is `'full'`.
+
+For most applications, `'full'` is the correct compilation mode.
+
+Use `'partial'` for independently published libraries, such as NPM packages.
+`'partial'` compilations output a stable, intermediate format which better supports usage by applications built at different Angular versions from the library.
+Libraries built at "HEAD" alongside their applications and using the same version of Angular such as in a mono-repository can use `'full'` since there is no risk of version skew.
+
+### `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.
+See [metadata rewriting](tools/cli/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 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 create legacy ids for messages that are tagged in templates by the `i18n` attribute.
+See [Mark text for translations][GuideI18nCommonPrepareMarkTextInComponentTemplate] for more information about marking messages for localization.
+
+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 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 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`
+
+When `true`, replaces the `templateUrl` and `styleUrls` properties in all `@Component` decorators with inline content in the `template` and `styles` properties.
+
+When enabled, the `.js` output of `ngc` does not include any lazy-loaded template or style URLs.
+
+For library projects created with the Angular CLI, the development configuration default is `true`.
+
+### `enableLegacyTemplate`
+
+When `true`, enables the deprecated `<template>` element in place of `<ng-template>`.
+Default is `false`.
+Might be required by some third-party Angular libraries.
+
+### `flatModuleId`
+
+The module ID to use for importing a flat module \(when `flatModuleOutFile` is `true`\).
+References created by the template compiler use this module name when importing symbols from the flat module.
+Ignored if `flatModuleOutFile` is `false`.
+
+### `flatModuleOutFile`
+
+When `true`, generates a flat module index of the given filename and the corresponding flat module metadata.
+Use to create flat modules that are packaged similarly to `@angular/core` and `@angular/common`.
+When this option is used, the `package.json` for the library should refer to the created flat module index instead of the library index file.
+
+Produces only one `.metadata.json` file, which contains all the metadata necessary for symbols exported from the library index.
+In the created `.ngfactory.js` files, the flat module index is used to import symbols. Symbols that include both the public API from the library index and shrouded internal symbols.
+
+By default, the `.ts` file supplied in the `files` field is assumed to be the library index.
+If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
+If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced.
+
+A flat module index `.d.ts` and `.js` is created with the given `flatModuleOutFile` name in the same location as the library index `.d.ts` file.
+
+For example, if a library uses the `public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field would be `["public_api.ts"]`.
+The `flatModuleOutFile` option could then be set, for example, to `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files.
+The `module` field of the library's `package.json` would be `"index.js"` and the `typings` field would be `"index.d.ts"`.
+
+### `fullTemplateTypeCheck`
+
+When `true`, the recommended value, enables the [binding expression validation](tools/cli/aot-compiler#binding-expression-validation) phase of the template compiler. This phase uses TypeScript to verify binding expressions.
+For more information, see [Template type checking](tools/cli/template-typecheck).
+
+Default is `false`, but when you use the Angular CLI command `ng new --strict`, it is set to `true` in the new project's configuration.
+
+IMPORTANT: The `fullTemplateTypeCheck` option has been deprecated in Angular 13 in favor of the `strictTemplates` family of compiler options.
+
+### `generateCodeForLibraries`
+
+When `true`, creates factory files \(`.ngfactory.js` and `.ngstyle.js`\) for `.d.ts` files with a corresponding `.metadata.json` file. The default value is `true`.
+
+When `false`, factory files are created only for `.ts` files.
+Do this when using factory summaries.
+
+### `preserveWhitespaces`
+
+When `false`, the default, removes blank text nodes from compiled templates, which results in smaller emitted template factory modules.
+Set to `true` to preserve blank text nodes.
+
+HELPFUL: When using hydration, it is recommended that you use `preserveWhitespaces: false`, which is the default value. If you choose to enable preserving whitespaces by adding `preserveWhitespaces: true` to your tsconfig, it is possible you may encounter issues with hydration. This is not yet a fully supported configuration. Ensure this is also consistently set between the server and client tsconfig files. See the [hydration guide](guide/hydration#preserve-whitespaces) for more details.
+
+### `skipMetadataEmit`
+
+When `true`, does not produce `.metadata.json` files.
+Default is `false`.
+
+The `.metadata.json` files contain information needed by the template compiler from a `.ts` file that is not included in the `.d.ts` file produced by the TypeScript compiler.
+This information includes, for example, the content of annotations, such as a component's template, which TypeScript emits to the `.js` file but not to the `.d.ts` file.
+
+You can set to `true` when using factory summaries, because the factory summaries include a copy of the information that is in the `.metadata.json` file.
+
+Set to `true` if you are using TypeScript's `--outFile` option, because the metadata files are not valid for this style of TypeScript output.
+The Angular community does not recommend using `--outFile` with Angular.
+Use a bundler, such as [webpack](https://webpack.js.org), instead.
+
+### `skipTemplateCodegen`
+
+When `true`, does not emit `.ngfactory.js` and `.ngstyle.js` files.
+This turns off most of the template compiler and disables the reporting of template diagnostics.
+
+Can be used to instruct the template compiler to produce `.metadata.json` files for distribution with an `npm` package. This avoids the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to `npm`.
+
+For library projects created with the Angular CLI, the development configuration default is `true`.
+
+### `strictMetadataEmit`
+
+When `true`, reports an error to the `.metadata.json` file if `"skipMetadataEmit"` is `false`.
+Default is `false`.
+Use only when `"skipMetadataEmit"` is `false` and `"skipTemplateCodegen"` is `true`.
+
+This option is intended to verify the `.metadata.json` files emitted for bundling with an `npm` package.
+The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler.
+You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
+
+It is valid for `.metadata.json` files to contain errors.
+The template compiler reports these errors if the metadata is used to determine the contents of an annotation.
+The metadata collector cannot predict the symbols that are designed for use in an annotation. It preemptively includes error nodes in the metadata for the exported symbols.
+The template compiler can then use the error nodes to report an error if these symbols are used.
+
+If the client of a library intends to use a symbol in an annotation, the template compiler does not normally report this. It gets reported after the client actually uses the symbol.
+This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves.
+
+For library projects created with the Angular CLI, the development configuration default is `true`.
+
+### `strictInjectionParameters`
+
+When `true`, reports an error for a supplied parameter whose injection type cannot be determined.
+When `false`, constructor parameters of classes marked with `@Injectable` whose type cannot be resolved produce a warning.
+The recommended value is `true`, but the default value is `false`.
+
+When you use the Angular CLI command `ng new --strict`, it is set to `true` in the created project's configuration.
+
+### `strictTemplates`
+
+When `true`, enables [strict template type checking](tools/cli/template-typecheck#strict-mode).
+
+The strictness flags that this option enables allow you to turn on and off specific types of strict template type checking.
+See [troubleshooting template errors](tools/cli/template-typecheck#troubleshooting-template-errors).
+
+When you use the Angular CLI command `ng new --strict`, it is set to `true` in the new project's configuration.
+
+### `strictStandalone`
+
+When `true`, reports an error if a component, directive, or pipe is not standalone.
+
+### `trace`
+
+When `true`, prints extra information while compiling templates.
+Default is `false`.
+
+## Command line options
+
+Most of the time, you interact with the Angular Compiler indirectly using [Angular CLI](reference/configs/angular-compiler-options). When debugging certain issues, you might find it useful to invoke the Angular Compiler directly.
+You can use the `ngc` command provided by the `@angular/compiler-cli` npm package to call the compiler from the command line.
+
+The `ngc` command is a wrapper around TypeScript's `tsc` compiler command. The Angular Compiler is primarily configured through `tsconfig.json` while Angular CLI is primarily configured through `angular.json`.
+
+Besides the configuration file, you can also use [`tsc` command line options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to configure `ngc`.
+
+[GuideI18nCommonPrepareMarkTextInComponentTemplate]: guide/i18n/prepare#mark-text-in-component-template 'Mark text in component template - Prepare component for translation | Angular'