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

[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.

[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.

[hheexx]

Hi @alan-agius4 ,

looks like this feature was not present in builds before RC.
Now it's inside so I took a look.

I added to angular.json like this:

Slashes made a problem and generated manifest was:
export default {
basePath: '/',
supportedLocales: {
"en": "en",
"sr": "",
"ru": "/ru/"
},
entryPoints: {
'en': () => import('./en/main.server.mjs'),
'': () => import('./main.server.mjs'),
'/ru/': () => import('.//ru//main.server.mjs')
},
};

Russian was not working.
After removing the slashes everything is OK but maybe you want to check why is there different handling between en and ru.

[alan-agius4]

@hheexx, it looks like the validation function was not being called correctly. #29328

i18n.subPath is not a valid options, the subpath for the sourceLocale needs to be specified in i18n.sourceLocale.subPath. In this case, it worked as it fallbacked to the default value which is en for en. When the subPath is the same as the local code, it does not need to be specified.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}