From 32f91316d0d35eb01f0b64125b9cf9b8c56bb2c4 Mon Sep 17 00:00:00 2001 From: arturovt Date: Wed, 20 May 2026 18:23:30 +0300 Subject: [PATCH] docs: document i18n object forms for sourceLocale and locales in angular.json The `sourceLocale` and `locales` entries in `angular.json` accept object forms (with `code`, `baseHref`, and `subPath`) that were never documented. - Add an `i18n options` reference section to workspace-config.md covering the full shape of `sourceLocale` and each `locales` entry, including the distinction between `baseHref` (HTML only) and `subPath` (HTML + output directory name) - Add `i18n` to the project configuration options table in workspace-config.md - Expand the suboptions table in merge.md to mention the object forms and link to the new reference section Closes #59664 --- adev/src/content/guide/i18n/merge.md | 11 +++-- .../reference/configs/workspace-config.md | 48 +++++++++++++++---- 2 files changed, 47 insertions(+), 12 deletions(-) diff --git a/adev/src/content/guide/i18n/merge.md b/adev/src/content/guide/i18n/merge.md index a78d6632609f..2a819e5ce14c 100644 --- a/adev/src/content/guide/i18n/merge.md +++ b/adev/src/content/guide/i18n/merge.md @@ -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 @@ -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' diff --git a/adev/src/content/reference/configs/workspace-config.md b/adev/src/content/reference/configs/workspace-config.md index 151c4b8b799d..322310abd8c5 100644 --- a/adev/src/content/reference/configs/workspace-config.md +++ b/adev/src/content/reference/configs/workspace-config.md @@ -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 `` 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 `` 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 `` 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 `` 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