Skip to content

docs: document i18n object forms for sourceLocale and locales in angular.json #68822

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
arturovt wants to merge 1 commit into
base: main
Choose a base branch
from
+47 −12
Open

docs: document i18n object forms for sourceLocale and locales in angular.json #68822

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions adev/src/content/guide/i18n/merge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,12 @@ Use the `i18n` project option in the [`angular.json`][GuideWorkspaceConfig] work

The following sub-options identify the source language and tell the compiler where to find supported translations for the project.

| Suboption | Details |
| :------------- | :--------------------------------------------------------------------------- |
| `sourceLocale` | The locale you use within the application source code \(`en-US` by default\) |
| `locales` | A map of locale identifiers to translation files |
| Suboption | Details |
| :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceLocale` | The locale you use within the application source code \(`en-US` by default\). Can also be an object with `code`, `baseHref`, and `subPath` properties. |
| `locales` | A map of locale identifiers to translation files. Each entry can also be an object with `translation`, `baseHref`, and `subPath` properties. |

For the full list of `i18n` properties and their types, see [i18n options][GuideWorkspaceConfigI18n].

### `angular.json` for `en-US` and `fr` example

Expand Down Expand Up @@ -149,3 +151,4 @@ TLDR: Compile once, then translate for each locale.
[GuideI18nCommonMergeGenerateApplicationVariantsForEachLocale]: guide/i18n/merge#generate-application-variants-for-each-locale 'Generate application variants for each locale - Merge translations into the application | Angular'
[GuideI18nCommonTranslationFilesChangeTheSourceLanguageFileFormat]: guide/i18n/translation-files#change-the-source-language-file-format 'Change the source language file format - Work with translation files | Angular'
[GuideWorkspaceConfig]: reference/configs/workspace-config 'Angular workspace configuration | Angular'
[GuideWorkspaceConfigI18n]: reference/configs/workspace-config#i18n-options 'i18n options - Angular workspace configuration | Angular'
48 changes: 40 additions & 8 deletions adev/src/content/reference/configs/workspace-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,14 +62,46 @@ The following properties are a set of options that customize the Angular CLI.

The following top-level configuration properties are available for each project, under `projects['project-name']`.

| Property | Details | Value type | Default value |
| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | :-------------- |
| `root` | The root directory for this project's files, relative to the workspace directory. Empty for the initial application, which resides at the top level of the workspace. | `string` | None (required) |
| `projectType` | One of "application" or "library" An application can run independently in a browser, while a library cannot. | `application` \| `library` | None (required) |
| `sourceRoot` | The root directory for this project's source files. | `string` | `''` |
| `prefix` | A string that Angular prepends to selectors when generating new components, directives, and pipes using `ng generate`. Can be customized to identify an application or feature area. | `string` | `'app'` |
| `schematics` | A set of schematics that customize the `ng generate` sub-command option defaults for this project. See the [Generation schematics](#schematics) section. | See [schematics](#schematics) | `{}` |
| `architect` | Configuration defaults for Architect builder targets for this project. | See [Configuring builder targets](#configuring-builder-targets) | `{}` |
| Property | Details | Value type | Default value |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | :-------------- |
| `root` | The root directory for this project's files, relative to the workspace directory. Empty for the initial application, which resides at the top level of the workspace. | `string` | None (required) |
| `projectType` | One of "application" or "library" An application can run independently in a browser, while a library cannot. | `application` \| `library` | None (required) |
| `sourceRoot` | The root directory for this project's source files. | `string` | `''` |
| `prefix` | A string that Angular prepends to selectors when generating new components, directives, and pipes using `ng generate`. Can be customized to identify an application or feature area. | `string` | `'app'` |
| `i18n` | Internationalization options for the project. Defines the source locale and additional locales to build. See [Define locales in the build configuration](guide/i18n/merge#define-locales-in-the-build-configuration). | See [i18n options](#i18n-options) | `{}` |
| `schematics` | A set of schematics that customize the `ng generate` sub-command option defaults for this project. See the [Generation schematics](#schematics) section. | See [schematics](#schematics) | `{}` |
| `architect` | Configuration defaults for Architect builder targets for this project. | See [Configuring builder targets](#configuring-builder-targets) | `{}` |

## i18n options

Use the `i18n` project option to define the application's source locale and any additional locales to build.

| Property | Details | Value type | Default value |
| :------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------ |
| `sourceLocale` | The locale used in the application source code. Can be a locale identifier string or a [configuration object](#sourcelocale-object). | `string` \| [sourceLocale object](#sourcelocale-object) | `"en-US"` |
| `locales` | A map of locale identifiers to translation files or [locale configuration objects](#locale-object). | `object` | `{}` |

### `sourceLocale` object

Pass an object instead of a string to customize the output directory or base HREF for the source locale:

| Property | Details | Value type | Default value |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | :------------ |
| `code` | The source locale identifier. | `string` | `"en-US"` |
| `baseHref` | Overrides the HTML `<base href>` for this locale. The output directory name stays as the locale code. Cannot be used together with `subPath`. | `string` | Locale code |
| `subPath` | Sets both the output directory name and the HTML `<base href>` for this locale. Cannot be used together with `baseHref`. | `string` | Locale code |

### Locale object

Each `locales` entry can be a path string, an array of paths, or an object:

| Property | Details | Value type | Default value |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------- | :------------ |
| `translation` | Path or paths to the translation file(s) for this locale. | `string` \| `string[]` | |
| `baseHref` | Overrides the HTML `<base href>` for this locale. The output directory name stays as the locale identifier. Cannot be used together with `subPath`. | `string` | Locale code |
| `subPath` | Sets both the output directory name and the HTML `<base href>` for this locale. Cannot be used together with `baseHref`. | `string` | Locale code |

HELPFUL: Use `subPath` rather than `baseHref` when you also need to rename the output directory — for example, to output to `de-DE/` instead of `de/`.

## Schematics

Expand Down
Loading