Skip to content

Commit 004b9a2

Browse files
oidacraoidacra
committed
translate: translation for configuration guides
Fixes #127
1 parent e5dc343 commit 004b9a2

File tree

8 files changed

+1442
-477
lines changed

8 files changed

+1442
-477
lines changed

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

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Angular compiler options
2+
3+
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).
4+
5+
The Angular options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler.
6+
7+
<docs-code header="tsconfig.json" path="adev/src/content/examples/angular-compiler-options/tsconfig.json" visibleRegion="angular-compiler-options"/>
8+
9+
## Configuration inheritance with `extends`
10+
11+
Like the TypeScript compiler, the Angular AOT compiler also supports `extends` in the `angularCompilerOptions` section of the TypeScript configuration file.
12+
The `extends` property is at the top level, parallel to `compilerOptions` and `angularCompilerOptions`.
13+
14+
A TypeScript configuration can inherit settings from another file using the `extends` property.
15+
The configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file.
16+
17+
For example:
18+
19+
<docs-code header="tsconfig.app.json" path="adev/src/content/examples/angular-compiler-options/tsconfig.app.json" visibleRegion="angular-compiler-options-app"/>
20+
21+
For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
22+
23+
## Template options
24+
25+
The following options are available for configuring the Angular AOT compiler.
26+
27+
### `annotationsAs`
28+
29+
Modifies how Angular-specific annotations are emitted to improve tree-shaking.
30+
Non-Angular annotations are not affected.
31+
One of `static fields` or `decorators`. The default value is `static fields`.
32+
33+
- 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
34+
- The `decorators` value leaves the decorators in place, which makes compilation faster.
35+
TypeScript emits calls to the `__decorate` helper.
36+
Use `--emitDecoratorMetadata` for runtime reflection.
37+
38+
HELPFUL: That the resulting code cannot tree-shake properly.
39+
40+
### `annotateForClosureCompiler`
41+
42+
<!-- vale Angular.Angular_Spelling = NO -->
43+
44+
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).
45+
Default is `false`.
46+
47+
<!-- vale Angular.Angular_Spelling = YES -->
48+
49+
### `compilationMode`
50+
51+
Specifies the compilation mode to use.
52+
The following modes are available:
53+
54+
| Modes | Details |
55+
| :---------- | :-------------------------------------------------------------------------------------------------- |
56+
| `'full'` | Generates fully AOT-compiled code according to the version of Angular that is currently being used. |
57+
| `'partial'` | Generates code in a stable, but intermediate form suitable for a published library. |
58+
59+
The default value is `'full'`.
60+
61+
For most applications, `'full'` is the correct compilation mode.
62+
63+
Use `'partial'` for independently published libraries, such as NPM packages.
64+
`'partial'` compilations output a stable, intermediate format which better supports usage by applications built at different Angular versions from the library.
65+
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.
66+
67+
### `disableExpressionLowering`
68+
69+
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.
70+
See [metadata rewriting](tools/cli/aot-compiler#metadata-rewriting) for more information.
71+
72+
When `false`, disables this rewriting, requiring the rewriting to be done manually.
73+
74+
### `disableTypeScriptVersionCheck`
75+
76+
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.
77+
Not recommended, as unsupported versions of TypeScript might have undefined behavior.
78+
Default is `false`.
79+
80+
### `enableI18nLegacyMessageIdFormat`
81+
82+
Instructs the Angular template compiler to create legacy ids for messages that are tagged in templates by the `i18n` attribute.
83+
See [Mark text for translations][GuideI18nCommonPrepareMarkTextInComponentTemplate] for more information about marking messages for localization.
84+
85+
Set this option to `false` unless your project relies upon translations that were created earlier using legacy IDs.
86+
Default is `true`.
87+
88+
The pre-Ivy message extraction tooling created a variety of legacy formats for extracted message IDs.
89+
These message formats have some issues, such as whitespace handling and reliance upon information inside the original HTML of a template.
90+
91+
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`.
92+
This allows `$localize` messages in application code to use the same ID as identical `i18n` messages in component templates.
93+
94+
### `enableResourceInlining`
95+
96+
When `true`, replaces the `templateUrl` and `styleUrls` properties in all `@Component` decorators with inline content in the `template` and `styles` properties.
97+
98+
When enabled, the `.js` output of `ngc` does not include any lazy-loaded template or style URLs.
99+
100+
For library projects created with the Angular CLI, the development configuration default is `true`.
101+
102+
### `enableLegacyTemplate`
103+
104+
When `true`, enables the deprecated `<template>` element in place of `<ng-template>`.
105+
Default is `false`.
106+
Might be required by some third-party Angular libraries.
107+
108+
### `flatModuleId`
109+
110+
The module ID to use for importing a flat module \(when `flatModuleOutFile` is `true`\).
111+
References created by the template compiler use this module name when importing symbols from the flat module.
112+
Ignored if `flatModuleOutFile` is `false`.
113+
114+
### `flatModuleOutFile`
115+
116+
When `true`, generates a flat module index of the given filename and the corresponding flat module metadata.
117+
Use to create flat modules that are packaged similarly to `@angular/core` and `@angular/common`.
118+
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.
119+
120+
Produces only one `.metadata.json` file, which contains all the metadata necessary for symbols exported from the library index.
121+
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.
122+
123+
By default, the `.ts` file supplied in the `files` field is assumed to be the library index.
124+
If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
125+
If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced.
126+
127+
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.
128+
129+
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"]`.
130+
The `flatModuleOutFile` option could then be set, for example, to `"index.js"`, which produces `index.d.ts` and `index.metadata.json` files.
131+
The `module` field of the library's `package.json` would be `"index.js"` and the `typings` field would be `"index.d.ts"`.
132+
133+
### `fullTemplateTypeCheck`
134+
135+
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.
136+
For more information, see [Template type checking](tools/cli/template-typecheck).
137+
138+
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.
139+
140+
IMPORTANT: The `fullTemplateTypeCheck` option has been deprecated in Angular 13 in favor of the `strictTemplates` family of compiler options.
141+
142+
### `generateCodeForLibraries`
143+
144+
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`.
145+
146+
When `false`, factory files are created only for `.ts` files.
147+
Do this when using factory summaries.
148+
149+
### `preserveWhitespaces`
150+
151+
When `false`, the default, removes blank text nodes from compiled templates, which results in smaller emitted template factory modules.
152+
Set to `true` to preserve blank text nodes.
153+
154+
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.
155+
156+
### `skipMetadataEmit`
157+
158+
When `true`, does not produce `.metadata.json` files.
159+
Default is `false`.
160+
161+
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.
162+
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.
163+
164+
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.
165+
166+
Set to `true` if you are using TypeScript's `--outFile` option, because the metadata files are not valid for this style of TypeScript output.
167+
The Angular community does not recommend using `--outFile` with Angular.
168+
Use a bundler, such as [webpack](https://webpack.js.org), instead.
169+
170+
### `skipTemplateCodegen`
171+
172+
When `true`, does not emit `.ngfactory.js` and `.ngstyle.js` files.
173+
This turns off most of the template compiler and disables the reporting of template diagnostics.
174+
175+
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`.
176+
177+
For library projects created with the Angular CLI, the development configuration default is `true`.
178+
179+
### `strictMetadataEmit`
180+
181+
When `true`, reports an error to the `.metadata.json` file if `"skipMetadataEmit"` is `false`.
182+
Default is `false`.
183+
Use only when `"skipMetadataEmit"` is `false` and `"skipTemplateCodegen"` is `true`.
184+
185+
This option is intended to verify the `.metadata.json` files emitted for bundling with an `npm` package.
186+
The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler.
187+
You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
188+
189+
It is valid for `.metadata.json` files to contain errors.
190+
The template compiler reports these errors if the metadata is used to determine the contents of an annotation.
191+
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.
192+
The template compiler can then use the error nodes to report an error if these symbols are used.
193+
194+
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.
195+
This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves.
196+
197+
For library projects created with the Angular CLI, the development configuration default is `true`.
198+
199+
### `strictInjectionParameters`
200+
201+
When `true`, reports an error for a supplied parameter whose injection type cannot be determined.
202+
When `false`, constructor parameters of classes marked with `@Injectable` whose type cannot be resolved produce a warning.
203+
The recommended value is `true`, but the default value is `false`.
204+
205+
When you use the Angular CLI command `ng new --strict`, it is set to `true` in the created project's configuration.
206+
207+
### `strictTemplates`
208+
209+
When `true`, enables [strict template type checking](tools/cli/template-typecheck#strict-mode).
210+
211+
The strictness flags that this option enables allow you to turn on and off specific types of strict template type checking.
212+
See [troubleshooting template errors](tools/cli/template-typecheck#troubleshooting-template-errors).
213+
214+
When you use the Angular CLI command `ng new --strict`, it is set to `true` in the new project's configuration.
215+
216+
### `strictStandalone`
217+
218+
When `true`, reports an error if a component, directive, or pipe is not standalone.
219+
220+
### `trace`
221+
222+
When `true`, prints extra information while compiling templates.
223+
Default is `false`.
224+
225+
## Command line options
226+
227+
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.
228+
You can use the `ngc` command provided by the `@angular/compiler-cli` npm package to call the compiler from the command line.
229+
230+
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`.
231+
232+
Besides the configuration file, you can also use [`tsc` command line options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to configure `ngc`.
233+
234+
[GuideI18nCommonPrepareMarkTextInComponentTemplate]: guide/i18n/prepare#mark-text-in-component-template 'Mark text in component template - Prepare component for translation | Angular'

0 commit comments

Comments
 (0)