feat(@angular/ssr): redirect to preferred locale when accessing root route without a specified locale

When users access the root route `/` without providing a locale, the application now redirects them to their preferred locale based on the `Accept-Language` header.

This enhancement leverages the user's browser preferences to determine the most appropriate locale, providing a seamless and personalized experience without requiring manual locale selection.

Author: alan-agius4

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

@@ -57,15 +57,21 @@ export function generateAngularServerAppEngineManifest(
     for (const locale of i18nOptions.inlineLocales) {
       const { urlSegment = locale } = i18nOptions.locales[locale];
       const importPath = `${urlSegment ? `${urlSegment}/` : ''}${MAIN_SERVER_OUTPUT_FILENAME}`;
-      entryPoints[urlSegment] = `() => import('./${importPath}')]`;
+      entryPoints[urlSegment] = `() => import('./${importPath}')`;
     }
   } else {
     entryPoints[''] = `() => import('./${MAIN_SERVER_OUTPUT_FILENAME}')`;
   }
 
+  // Remove trailing slash
+  let basePath = baseHref || '/';
+  if (basePath.length > 1 && basePath[basePath.length - 1] === '/') {
+    basePath = basePath.slice(0, -1);
+  }
+
   const manifestContent = `
 export default {
-  basePath: '${baseHref ?? '/'}',
+  basePath: '${basePath}',
   entryPoints: {
     ${Object.entries(entryPoints)
       .map(([key, value]) => `'${key}': ${value}`)

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

@@ -8,8 +8,9 @@
 
 import type { AngularServerApp, getOrCreateAngularServerApp } from './app';
 import { Hooks } from './hooks';
-import { getPotentialLocaleIdFromUrl } from './i18n';
+import { getPotentialLocaleIdFromUrl, getPreferredLocale } from './i18n';
 import { EntryPointExports, getAngularAppEngineManifest } from './manifest';
+import { joinUrlParts } from './utils/url';
 
 /**
  * Angular server application engine.
@@ -47,9 +48,9 @@ export class AngularAppEngine {
   private readonly manifest = getAngularAppEngineManifest();
 
   /**
-   * The number of entry points available in the server application's manifest.
+   * The keys of entry points available in the server application's manifest.
    */
-  private readonly entryPointsCount = Object.keys(this.manifest.entryPoints).length;
+  private readonly entryPointsLocales = new Set(Object.keys(this.manifest.entryPoints));
 
   /**
    * A cache that holds entry points, keyed by their potential locale string.
@@ -70,7 +71,43 @@ export class AngularAppEngine {
   async handle(request: Request, requestContext?: unknown): Promise<Response | null> {
     const serverApp = await this.getAngularServerAppForRequest(request);
 
-    return serverApp ? serverApp.handle(request, requestContext) : null;
+    if (serverApp) {
+      return serverApp.handle(request, requestContext);
+    }
+
+    if (this.entryPointsLocales.size > 1) {
+      return this.redirectBasedOnAcceptLanguage(request);
+    }
+
+    return null;
+  }
+
+  /**
+   * Handles requests for the base path when i18n is enabled.
+   * Redirects the user to a locale-specific path based on the `Accept-Language` header.
+   *
+   * @param request The incoming request.
+   * @returns A `Response` object with a 302 redirect, or `null` if i18n is not enabled
+   *          or the request is not for the base path.
+   */
+  private redirectBasedOnAcceptLanguage(request: Request): Response | null {
+    // If the request is not for the base path, it's not our responsibility to handle it.
+    const url = new URL(request.url);
+    if (url.pathname !== this.manifest.basePath) {
+      return null;
+    }
+
+    // For requests to the base path (typically '/'), attempt to extract the preferred locale
+    // from the 'Accept-Language' header.
+    const preferredLocale = getPreferredLocale(
+      request.headers.get('Accept-Language') || '*',
+      this.entryPointsLocales,
+    );
+
+    url.pathname = joinUrlParts(url.pathname, preferredLocale);
+
+    // Use a 302 redirect as language preference may change.
+    return Response.redirect(url, 302);
   }
 
   /**
@@ -142,7 +179,7 @@ export class AngularAppEngine {
    */
   private getEntryPointExportsForUrl(url: URL): Promise<EntryPointExports> | undefined {
     const { basePath } = this.manifest;
-    if (this.entryPointsCount === 1) {
+    if (this.entryPointsLocales.size === 1) {
       return this.getEntryPointExports('');
     }
 

packages/angular/ssr/src/i18n.ts

@@ -43,3 +43,107 @@ export function getPotentialLocaleIdFromUrl(url: URL, basePath: string): string
   // Extract the potential locale id.
   return pathname.slice(start, end);
 }
+
+/**
+ * Represents a locale preference with an optional quality value.
+ */
+interface LocalePreference {
+  /** The locale (e.g., 'en-US', 'fr') */
+  locale: string;
+
+  /** The quality value indicating the preference */
+  quality?: number;
+}
+
+/**
+ * Parses the `Accept-Language` header and returns a list of locale preferences with their respective quality values.
+ *
+ * @param header - The value of the `Accept-Language` header, typically a comma-separated list of locales with optional quality values.
+ * @returns A list of `LocalePreference` objects representing the parsed locales and their associated quality values.
+ *
+ * @example
+ * ```js
+ * parseLanguageHeader('en-US;q=0.8,fr-FR;q=0.9')
+ * // returns [{ locale: 'en-US', quality: 0.8 }, { locale: 'fr-FR', quality: 0.9 }]
+ * ```
+ */
+function parseLanguageHeader(header: string): LocalePreference[] {
+  if (header === '*') {
+    return [{ locale: '*', quality: undefined }];
+  }
+
+  const localesList: LocalePreference[] = [];
+  const items = header.split(',');
+
+  for (const item of items) {
+    const [locale, qualityValue] = item
+      .trim()
+      .split(';', 2)
+      .map((v) => v.trim());
+
+    const quality = qualityValue?.startsWith('q=') ? parseFloat(qualityValue.slice(2)) : undefined;
+
+    localesList.push({
+      locale,
+      quality: quality !== undefined && quality <= 1 ? quality : undefined,
+    });
+  }
+
+  return localesList;
+}
+
+/**
+ * Gets the preferred locale based on the highest quality value from the provided header and the set of available locales.
+ * If no exact match is found, it tries to find the closest match based on language prefixes.
+ *
+ * @param header - The `Accept-Language` header string to parse and evaluate.
+ * @param availableLocales - A readonly set of available locales that the user can choose from.
+ * @returns The best matching locale.
+ *
+ * @example
+ * ```js
+ * getPreferredLocale('en-US;q=0.8,fr-FR;q=0.9', new Set(['en-US', 'fr-FR', 'de-DE']))
+ * // returns 'fr-FR'
+ * ```
+ */
+export function getPreferredLocale(header: string, availableLocales: ReadonlySet<string>): string {
+  const parsedLocales = parseLanguageHeader(header);
+  if (
+    parsedLocales.length === 0 ||
+    (parsedLocales.length === 1 && parsedLocales[0].locale === '*')
+  ) {
+    return availableLocales.values().next().value as string;
+  }
+
+  let bestMatch: string | undefined;
+  let bestQuality = 0;
+
+  // Find the best exact match based on quality
+  for (const { locale, quality } of parsedLocales) {
+    const currentQuality = quality ?? 1;
+    if (availableLocales.has(locale) && currentQuality > bestQuality) {
+      bestMatch = locale;
+      bestQuality = currentQuality;
+    }
+  }
+
+  if (bestMatch) {
+    return bestMatch;
+  }
+
+  // If no exact match, fallback to closest matches
+  bestQuality = 0;
+  for (const { locale, quality } of parsedLocales) {
+    const currentQuality = quality ?? 1;
+    const languagePrefix = locale.split('-', 1)[0];
+    for (const availableLocale of availableLocales) {
+      if (availableLocale.startsWith(languagePrefix) && currentQuality > bestQuality) {
+        bestMatch = availableLocale;
+        bestQuality = currentQuality;
+        break;
+      }
+    }
+  }
+
+  return bestMatch || (availableLocales.values().next().value as string);
+}

packages/angular/ssr/test/app-engine_spec.ts

@@ -20,6 +20,13 @@ import { setAngularAppTestingManifest } from './testing-utils';
 
 function createEntryPoint(locale: string) {
   return async () => {
+    @Component({
+      standalone: true,
+      selector: `app-home-${locale}`,
+      template: `Home works ${locale.toUpperCase()}`,
+    })
+    class HomeComponent {}
+
     @Component({
       standalone: true,
       selector: `app-ssr-${locale}`,
@@ -38,6 +45,7 @@ function createEntryPoint(locale: string) {
       [
         { path: 'ssg', component: SSGComponent },
         { path: 'ssr', component: SSRComponent },
+        { path: '', component: HomeComponent },
       ],
       [
         { path: 'ssg', renderMode: RenderMode.Prerender },
@@ -83,7 +91,7 @@ describe('AngularAppEngine', () => {
           it: createEntryPoint('it'),
           en: createEntryPoint('en'),
         },
-        basePath: '',
+        basePath: '/',
       });
 
       appEngine = new AngularAppEngine();
@@ -132,6 +140,15 @@ describe('AngularAppEngine', () => {
         expect(response).toBeNull();
       });
 
+      it('should redirect to the highest priority locale when the URL is "/"', async () => {
+        const request = new Request('https://example.com/', {
+          headers: { 'Accept-Language': 'fr-CH, fr;q=0.9, it;q=0.8, en;q=0.7, *;q=0.5' },
+        });
+        const response = await appEngine.handle(request);
+        expect(response?.status).toBe(302);
+        expect(response?.headers.get('Location')).toBe('https://example.com/it');
+      });
+
       it('should return null for requests to file-like resources in a locale', async () => {
         const request = new Request('https://example.com/it/logo.png');
         const response = await appEngine.handle(request);
@@ -165,7 +182,7 @@ describe('AngularAppEngine', () => {
             };
           },
         },
-        basePath: '',
+        basePath: '/',
       });
 
       appEngine = new AngularAppEngine();

packages/angular/ssr/test/i18n_spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { getPotentialLocaleIdFromUrl } from '../src/i18n';
+import { getPotentialLocaleIdFromUrl, getPreferredLocale } from '../src/i18n';
 
 describe('getPotentialLocaleIdFromUrl', () => {
   it('should extract locale ID correctly when basePath is present', () => {
@@ -65,3 +65,71 @@ describe('getPotentialLocaleIdFromUrl', () => {
     expect(localeId).toBe('en');
   });
 });
+
+describe('getPreferredLocale', () => {
+  it('should return the exact match with the highest quality value', () => {
+    const header = 'en-GB;q=0.8,fr-FR;q=0.9';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'fr-BE']);
+    const result = getPreferredLocale(header, availableLocales);
+    // Exact match for 'fr-FR' with the highest quality (0.9)
+    expect(result).toBe('fr-FR');
+  });
+
+  it('should return the best match when no exact match is found, using language prefixes', () => {
+    const header = 'en-GB;q=0.9,fr;q=0.8';
+    const availableLocales = new Set(['fr-FR', 'de-DE', 'en-US']);
+    const result = getPreferredLocale(header, availableLocales);
+    // 'en-US' is the exact match with the highest quality (0.9)
+    expect(result).toBe('en-US');
+  });
+
+  it('should match based on language prefix when no exact match is found', () => {
+    const header = 'en-US;q=0.8,fr;q=0.9,en-GB;q=0.7';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'de-DE']);
+    const result = getPreferredLocale(header, availableLocales);
+    // Best match is 'en-GB' based on exact match (0.8 for 'en-US')
+    expect(result).toBe('en-GB');
+  });
+
+  it('should return the first available locale when no exact match or prefix is found', () => {
+    const header = 'it-IT;q=0.8';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'de-DE']);
+    const result = getPreferredLocale(header, availableLocales);
+    // The first locale in the availableLocales set
+    expect(result).toBe('en-GB');
+  });
+
+  it('should return the first available locale when the header is empty', () => {
+    const header = '';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'de-DE']);
+    const result = getPreferredLocale(header, availableLocales);
+    expect(result).toBe('en-GB'); // The first locale in the availableLocales set
+  });
+
+  it('should return the first available locale when the header is just "*"', () => {
+    const header = '*';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'de-DE']);
+    const result = getPreferredLocale(header, availableLocales);
+    // The first locale in the availableLocales set
+    expect(result).toBe('en-GB');
+  });
+
+  it('should return the first available locale when no valid languages are in header', () => {
+    const header = 'xyz;q=0.5';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'de-DE']);
+    const result = getPreferredLocale(header, availableLocales);
+    // No valid language, fallback to the first available locale
+    expect(result).toBe('en-GB');
+  });
+
+  it('should return the closest match when no valid languages in header', () => {
+    const header = 'en-XYZ;q=0.7,fr-XYZ;q=0.8';
+    const availableLocales = new Set(['en-GB', 'fr-FR', 'de-DE']);
+    const result = getPreferredLocale(header, availableLocales);
+
+    // Since there is no exact match for 'en-XYZ' or 'fr-XYZ',
+    // the function should return 'fr-FR' as the closest match,
+    // as it shares the language prefix 'fr' with the 'fr-XYZ' in the header.
+    expect(result).toBe('fr-FR');
+  });
+});