feat(@angular/build): add support for customizing URL segments with i18n

Previously, the `baseHref` option under each locale allowed for generating a unique base href for specific locales. However, users were still required to handle file organization manually, and `baseHref` appeared to be primarily designed for this purpose.

This commit introduces a new `urlSegment` option, which simplifies the i18n process, particularly in static site generation (SSG) and server-side rendering (SSR). When the `urlSegment` option is used, the `baseHref` is ignored. Instead, the `urlSegment` serves as both the base href and the name of the directory containing the localized version of the app.

### Configuration Example

Below is an example configuration showcasing the use of `urlSegment`:

```json
"i18n": {
  "sourceLocale": {
    "code": "en-US",
    "urlSegment": ""
  },
  "locales": {
    "fr-BE": {
      "urlSegment": "fr",
      "translation": "src/i18n/messages.fr-BE.xlf"
    },
    "de-BE": {
      "urlSegment": "de",
      "translation": "src/i18n/messages.de-BE.xlf"
    }
  }
}
```

### Example Directory Structure

The following tree structure demonstrates how the `urlSegment` organizes localized build output:
```
dist/
├── app/
│   └── browser/  # Default locale, accessible at `/`
│       ├── fr/  # Locale for `fr-BE`, accessible at `/fr`
│       └── de/  # Locale for `de-BE`, accessible at `/de`
```
Closes #16997 and closes #28967

Author: alan-agius4

packages/angular/build/src/builders/application/i18n.ts

@@ -36,12 +36,14 @@ export async function inlineI18n(
   warnings: string[];
   prerenderedRoutes: PrerenderedRoutesRecord;
 }> {
+  const { i18nOptions, optimizationOptions, baseHref } = options;
+
   // Create the multi-threaded inliner with common options and the files generated from the build.
   const inliner = new I18nInliner(
     {
-      missingTranslation: options.i18nOptions.missingTranslationBehavior ?? 'warning',
+      missingTranslation: i18nOptions.missingTranslationBehavior ?? 'warning',
       outputFiles: executionResult.outputFiles,
-      shouldOptimize: options.optimizationOptions.scripts,
+      shouldOptimize: optimizationOptions.scripts,
     },
     maxWorkers,
   );
@@ -60,19 +62,16 @@ export async function inlineI18n(
   const updatedOutputFiles = [];
   const updatedAssetFiles = [];
   try {
-    for (const locale of options.i18nOptions.inlineLocales) {
+    for (const locale of i18nOptions.inlineLocales) {
       // A locale specific set of files is returned from the inliner.
       const localeInlineResult = await inliner.inlineForLocale(
         locale,
-        options.i18nOptions.locales[locale].translation,
+        i18nOptions.locales[locale].translation,
       );
       const localeOutputFiles = localeInlineResult.outputFiles;
       inlineResult.errors.push(...localeInlineResult.errors);
       inlineResult.warnings.push(...localeInlineResult.warnings);
 
-      const baseHref =
-        getLocaleBaseHref(options.baseHref, options.i18nOptions, locale) ?? options.baseHref;
-
       const {
         errors,
         warnings,
@@ -82,7 +81,7 @@ export async function inlineI18n(
       } = await executePostBundleSteps(
         {
           ...options,
-          baseHref,
+          baseHref: getLocaleBaseHref(baseHref, i18nOptions, locale) ?? baseHref,
         },
         localeOutputFiles,
         executionResult.assetFiles,
@@ -94,16 +93,17 @@ export async function inlineI18n(
       inlineResult.errors.push(...errors);
       inlineResult.warnings.push(...warnings);
 
-      // Update directory with locale base
-      if (options.i18nOptions.flatOutput !== true) {
+      // Update directory with locale base or urlSegment
+      const urlSegment = i18nOptions.locales[locale]?.urlSegment ?? locale;
+      if (i18nOptions.flatOutput !== true) {
         localeOutputFiles.forEach((file) => {
-          file.path = join(locale, file.path);
+          file.path = join(urlSegment, file.path);
         });
 
         for (const assetFile of [...executionResult.assetFiles, ...additionalAssets]) {
           updatedAssetFiles.push({
             source: assetFile.source,
-            destination: join(locale, assetFile.destination),
+            destination: join(urlSegment, assetFile.destination),
           });
         }
       } else {
@@ -128,7 +128,7 @@ export async function inlineI18n(
   ];
 
   // Assets are only changed if not using the flat output option
-  if (options.i18nOptions.flatOutput !== true) {
+  if (!i18nOptions.flatOutput) {
     executionResult.assetFiles = updatedAssetFiles;
   }
 

packages/angular/build/src/builders/application/options.ts

@@ -643,17 +643,25 @@ function normalizeGlobalEntries(
 }
 
 export function getLocaleBaseHref(
-  baseHref: string | undefined,
+  baseHref: string | undefined = '',
   i18n: NormalizedApplicationBuildOptions['i18nOptions'],
   locale: string,
 ): string | undefined {
   if (i18n.flatOutput) {
     return undefined;
   }
 
-  if (i18n.locales[locale] && i18n.locales[locale].baseHref !== '') {
-    return urlJoin(baseHref || '', i18n.locales[locale].baseHref ?? `/${locale}/`);
+  const localeData = i18n.locales[locale];
+  if (!localeData) {
+    return undefined;
   }
 
-  return undefined;
+  let urlSegment = localeData.urlSegment;
+  if (urlSegment !== undefined) {
+    urlSegment += '/';
+  }
+
+  const baseHrefSuffix = urlSegment ?? localeData.baseHref;
+
+  return baseHrefSuffix !== '' ? urlJoin(baseHref, baseHrefSuffix ?? locale + '/') : undefined;
 }

packages/angular/build/src/utils/i18n-options.ts

@@ -18,6 +18,7 @@ export interface LocaleDescription {
   translation?: Record<string, unknown>;
   dataPath?: string;
   baseHref?: string;
+  urlSegment?: string;
 }
 
 export interface I18nOptions {
@@ -64,6 +65,16 @@ function ensureString(value: unknown, name: string): asserts value is string {
   }
 }
 
+function ensureValidateUrlSegment(value: unknown, name: string): asserts value is string {
+  ensureString(value, name);
+
+  if (!/^[\w-]*$/.test(value)) {
+    throw new Error(
+      `Project ${name} field is malformed. Expected to match pattern: '/^[\\w-]*$/'.`,
+    );
+  }
+}
+
 export function createI18nOptions(
   projectMetadata: { i18n?: unknown },
   inline?: boolean | string[],
@@ -82,8 +93,9 @@ export function createI18nOptions(
     },
   };
 
-  let rawSourceLocale;
-  let rawSourceLocaleBaseHref;
+  let rawSourceLocale: string | undefined;
+  let rawSourceLocaleBaseHref: string | undefined;
+  let rawUrlSegment: string | undefined;
   if (typeof metadata.sourceLocale === 'string') {
     rawSourceLocale = metadata.sourceLocale;
   } else if (metadata.sourceLocale !== undefined) {
@@ -98,6 +110,15 @@ export function createI18nOptions(
       ensureString(metadata.sourceLocale.baseHref, 'i18n sourceLocale baseHref');
       rawSourceLocaleBaseHref = metadata.sourceLocale.baseHref;
     }
+
+    if (metadata.sourceLocale.urlSegment !== undefined) {
+      ensureValidateUrlSegment(metadata.sourceLocale.urlSegment, 'i18n sourceLocale urlSegment');
+      rawUrlSegment = metadata.sourceLocale.urlSegment;
+    }
+
+    if (rawUrlSegment !== undefined && rawSourceLocaleBaseHref !== undefined) {
+      throw new Error(`i18n sourceLocale urlSegment and baseHref cannot be used togather.`);
+    }
   }
 
   if (rawSourceLocale !== undefined) {
@@ -108,21 +129,35 @@ export function createI18nOptions(
   i18n.locales[i18n.sourceLocale] = {
     files: [],
     baseHref: rawSourceLocaleBaseHref,
+    urlSegment: rawUrlSegment,
   };
 
   if (metadata.locales !== undefined) {
     ensureObject(metadata.locales, 'i18n locales');
 
     for (const [locale, options] of Object.entries(metadata.locales)) {
-      let translationFiles;
-      let baseHref;
+      let translationFiles: string[] | undefined;
+      let baseHref: string | undefined;
+      let urlSegment: string | undefined;
+
       if (options && typeof options === 'object' && 'translation' in options) {
         translationFiles = normalizeTranslationFileOption(options.translation, locale, false);
 
         if ('baseHref' in options) {
           ensureString(options.baseHref, `i18n locales ${locale} baseHref`);
           baseHref = options.baseHref;
         }
+
+        if ('urlSegment' in options) {
+          ensureString(options.urlSegment, `i18n locales ${locale} urlSegment`);
+          urlSegment = options.urlSegment;
+        }
+
+        if (urlSegment !== undefined && baseHref !== undefined) {
+          throw new Error(
+            `i18n locales ${locale} urlSegment and baseHref cannot be used togather.`,
+          );
+        }
       } else {
         translationFiles = normalizeTranslationFileOption(options, locale, true);
       }

packages/angular/build/src/utils/server-rendering/manifest.ts

@@ -62,7 +62,7 @@ export function generateAngularServerAppEngineManifest(
       const importPath =
         './' + (i18nOptions.flatOutput ? '' : locale + '/') + MAIN_SERVER_OUTPUT_FILENAME;
 
-      let localeWithBaseHref = getLocaleBaseHref('', i18nOptions, locale) || '/';
+      let localeWithBaseHref = getLocaleBaseHref('', i18nOptions, locale) || '';
 
       // Remove leading and trailing slashes.
       const start = localeWithBaseHref[0] === '/' ? 1 : 0;

packages/angular/cli/lib/config/workspace-schema.json

@@ -275,18 +275,42 @@
                 },
                 {
                   "type": "object",
-                  "description": "Localization options to use for the source locale",
+                  "description": "Localization options to use for the source locale.",
                   "properties": {
                     "code": {
                       "type": "string",
-                      "description": "Specifies the locale code of the source locale",
+                      "description": "Specifies the locale code of the source locale.",
                       "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z]{4})?(-([a-zA-Z]{2}|[0-9]{3}))?(-[a-zA-Z]{5,8})?(-x(-[a-zA-Z0-9]{1,8})+)?$"
                     },
                     "baseHref": {
                       "type": "string",
-                      "description": "HTML base HREF to use for the locale (defaults to the locale code)"
+                      "description": "Specifies the HTML base HREF for the locale. Defaults to the locale code if not provided."
+                    },
+                    "urlSegment": {
+                      "type": "string",
+                      "description": "Defines the URL segment for accessing this locale. It serves as the HTML base HREF and the directory name for the output. Defaults to the locale code if not specified.",
+                      "pattern": "^[\\w-]*$"
                     }
                   },
+                  "anyOf": [
+                    {
+                      "required": ["urlSegment"],
+                      "not": {
+                        "required": ["baseHref"]
+                      }
+                    },
+                    {
+                      "required": ["baseHref"],
+                      "not": {
+                        "required": ["urlSegment"]
+                      }
+                    },
+                    {
+                      "not": {
+                        "required": ["baseHref", "urlSegment"]
+                      }
+                    }
+                  ],
                   "additionalProperties": false
                 }
               ]
@@ -299,29 +323,29 @@
                   "oneOf": [
                     {
                       "type": "string",
-                      "description": "Localization file to use for i18n"
+                      "description": "Localization file to use for i18n."
                     },
                     {
                       "type": "array",
-                      "description": "Localization files to use for i18n",
+                      "description": "Localization files to use for i18n.",
                       "items": {
                         "type": "string",
                         "uniqueItems": true
                       }
                     },
                     {
                       "type": "object",
-                      "description": "Localization options to use for the locale",
+                      "description": "Localization options to use for the locale.",
                       "properties": {
                         "translation": {
                           "oneOf": [
                             {
                               "type": "string",
-                              "description": "Localization file to use for i18n"
+                              "description": "Localization file to use for i18n."
                             },
                             {
                               "type": "array",
-                              "description": "Localization files to use for i18n",
+                              "description": "Localization files to use for i18n.",
                               "items": {
                                 "type": "string",
                                 "uniqueItems": true
@@ -331,9 +355,33 @@
                         },
                         "baseHref": {
                           "type": "string",
-                          "description": "HTML base HREF to use for the locale (defaults to the locale code)"
+                          "description": "Specifies the HTML base HREF for the locale. Defaults to the locale code if not provided."
+                        },
+                        "urlSegment": {
+                          "type": "string",
+                          "description": "Defines the URL segment for accessing this locale. It serves as the HTML base HREF and the directory name for the output. Defaults to the locale code if not specified.",
+                          "pattern": "^[\\w-]*$"
                         }
                       },
+                      "anyOf": [
+                        {
+                          "required": ["urlSegment"],
+                          "not": {
+                            "required": ["baseHref"]
+                          }
+                        },
+                        {
+                          "required": ["baseHref"],
+                          "not": {
+                            "required": ["urlSegment"]
+                          }
+                        },
+                        {
+                          "not": {
+                            "required": ["baseHref", "urlSegment"]
+                          }
+                        }
+                      ],
                       "additionalProperties": false
                     }
                   ]

packages/angular/ssr/src/app-engine.ts

@@ -143,6 +143,6 @@ export class AngularAppEngine {
 
     const potentialLocale = getPotentialLocaleIdFromUrl(url, basePath);
 
-    return this.getEntryPointExports(potentialLocale);
+    return this.getEntryPointExports(potentialLocale) ?? this.getEntryPointExports('');
   }
 }