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

[alan-agius4]

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 subPath option, which simplifies the i18n process, particularly in static site generation (SSG) and server-side rendering (SSR). When the subPath option is used, the baseHref is ignored. Instead, the subPath serves as both the base href and the name of the directory containing the localized version of the app.

Below is an example configuration showcasing the use of subPath:

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

The following tree structure demonstrates how the subPath 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`

DEPRECATED: The baseHref option under i18n.locales and i18n.sourceLocale in angular.json is deprecated in favor of subPath.

The subPath defines the URL segment for the locale, serving as both the HTML base HREF and the directory name for output. By default, if not specified, subPath will use the locale code.

Closes #16997 and closes #28967

[alan-agius4]

Should be deprecate this baseHref when using the application builder?

[dgp1130]

+1 to deprecating.

[dgp1130]

This looks great! Mostly just some small suggestions to make sure the error cases are clear and understandable to users.

My one thought is whether there is a more clear name than urlSegment we could use? In my mind that really doesn't describe what this will do and without any further context I'd have no idea what to use it for.

"segment" to me also implies it is exactly one segment between slashes, but I'm not sure that's a hard constraint? Users can write urlSegment: 'foo/bar' right? That would look like two segments to me.

Not really sure of an alternative, but we could consider something like localeBase, localeRoot, root (maybe we can rely on the context that this option is only available with a locale), directory, outputDir, subpath, localeBaseHref / baseHref (it does say this serves as "baseHref" in the JSON doc), ...

I'll defer to you on the exact naming, I just want to make sure we're considering alternatives and thinking critically about what this concept represents to users.

[dgp1130]

+1 to deprecating.

[alan-agius4]

I went with subPath for naming.

[clydin]

One option validation comment, otherwise LGTM.

[hheexx]

Is this going to Angular 20 or 19.1?

[alan-agius4]

19.1, which is currently in prerelease.