create-nextblock 0.12.14 → 0.12.15

package/templates/nextblock-template/lib/i18n/detection.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_LANGUAGE_DETECTION_SETTINGS,
+  detectLocaleFromBrowser,
+  detectLocaleFromCountry,
+  getCountryFromRequestHeaders,
+  matchLocale,
+  normalizeLanguageDetectionSettings,
+  parseAcceptLanguage,
+  resolveDetectedLocale,
+} from './detection';
+
+function headersOf(record: Record<string, string>) {
+  const lower = Object.fromEntries(
+    Object.entries(record).map(([key, value]) => [key.toLowerCase(), value]),
+  );
+  return { get: (name: string) => lower[name.toLowerCase()] ?? null };
+}
+
+describe('normalizeLanguageDetectionSettings', () => {
+  it('returns defaults for absent or malformed values', () => {
+    expect(normalizeLanguageDetectionSettings(null)).toEqual(DEFAULT_LANGUAGE_DETECTION_SETTINGS);
+    expect(normalizeLanguageDetectionSettings(undefined)).toEqual(
+      DEFAULT_LANGUAGE_DETECTION_SETTINGS,
+    );
+    expect(normalizeLanguageDetectionSettings('browser')).toEqual(
+      DEFAULT_LANGUAGE_DETECTION_SETTINGS,
+    );
+    expect(normalizeLanguageDetectionSettings([])).toEqual(DEFAULT_LANGUAGE_DETECTION_SETTINGS);
+  });
+
+  it('keeps valid fields and coerces invalid ones individually', () => {
+    expect(
+      normalizeLanguageDetectionSettings({ mode: 'country', rememberVisitorChoice: false }),
+    ).toEqual({ mode: 'country', rememberVisitorChoice: false });
+    expect(
+      normalizeLanguageDetectionSettings({ mode: 'ip-magic', rememberVisitorChoice: false }),
+    ).toEqual({ mode: 'browser', rememberVisitorChoice: false });
+    expect(
+      normalizeLanguageDetectionSettings({ mode: 'default', rememberVisitorChoice: 'yes' }),
+    ).toEqual({ mode: 'default', rememberVisitorChoice: true });
+  });
+});
+
+describe('parseAcceptLanguage', () => {
+  it('parses tags sorted by q-value with defaults', () => {
+    expect(parseAcceptLanguage('fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7')).toEqual([
+      { tag: 'fr-ch', base: 'fr', quality: 1 },
+      { tag: 'fr', base: 'fr', quality: 0.9 },
+      { tag: 'en', base: 'en', quality: 0.8 },
+      { tag: 'de', base: 'de', quality: 0.7 },
+    ]);
+  });
+
+  it('drops wildcards, q=0 entries, and malformed tags', () => {
+    expect(parseAcceptLanguage('*, en;q=0, <script>;q=1, fr')).toEqual([
+      { tag: 'fr', base: 'fr', quality: 1 },
+    ]);
+  });
+
+  it('handles empty and missing headers', () => {
+    expect(parseAcceptLanguage(null)).toEqual([]);
+    expect(parseAcceptLanguage('')).toEqual([]);
+  });
+
+  it('keeps original order among equal q-values', () => {
+    expect(parseAcceptLanguage('es, pt').map((entry) => entry.tag)).toEqual(['es', 'pt']);
+  });
+});
+
+describe('matchLocale', () => {
+  it('prefers exact matches, case-insensitively', () => {
+    expect(matchLocale(['fr-ca'], ['en', 'fr-CA'])).toBe('fr-CA');
+  });
+
+  it('falls back from a regional candidate to its base language', () => {
+    expect(matchLocale(['fr-CA'], ['en', 'fr'])).toBe('fr');
+  });
+
+  it('matches a base candidate to a regional site code', () => {
+    expect(matchLocale(['pt'], ['en', 'pt-BR'])).toBe('pt-BR');
+  });
+
+  it('respects candidate priority over match quality', () => {
+    // First candidate only base-matches, but it still beats later exact matches.
+    expect(matchLocale(['de-AT', 'en'], ['en', 'de'])).toBe('de');
+  });
+
+  it('returns null when nothing matches', () => {
+    expect(matchLocale(['ja', 'ko'], ['en', 'fr'])).toBeNull();
+    expect(matchLocale([], ['en'])).toBeNull();
+    expect(matchLocale(['en'], [])).toBeNull();
+  });
+});
+
+describe('detectLocaleFromBrowser', () => {
+  it('uses q-value order against the site languages', () => {
+    expect(detectLocaleFromBrowser('de;q=0.5, fr;q=0.9', ['en', 'fr', 'de'])).toBe('fr');
+  });
+
+  it('returns null without a usable header', () => {
+    expect(detectLocaleFromBrowser(null, ['en'])).toBeNull();
+    expect(detectLocaleFromBrowser('ja', ['en'])).toBeNull();
+  });
+});
+
+describe('detectLocaleFromCountry', () => {
+  it('maps countries to their primary languages in order', () => {
+    expect(detectLocaleFromCountry('FR', ['en', 'fr'])).toBe('fr');
+    expect(detectLocaleFromCountry('BR', ['en', 'pt'])).toBe('pt');
+    // Belgium lists nl before fr; the site only offers fr.
+    expect(detectLocaleFromCountry('BE', ['en', 'fr'])).toBe('fr');
+    expect(detectLocaleFromCountry('be', ['nl', 'fr'])).toBe('nl');
+  });
+
+  it('returns null for unknown countries or unmatched languages', () => {
+    expect(detectLocaleFromCountry('ZZ', ['en'])).toBeNull();
+    expect(detectLocaleFromCountry('JP', ['en', 'fr'])).toBeNull();
+    expect(detectLocaleFromCountry(null, ['en'])).toBeNull();
+  });
+});
+
+describe('getCountryFromRequestHeaders', () => {
+  it('reads host geo headers in precedence order', () => {
+    expect(getCountryFromRequestHeaders(headersOf({ 'x-vercel-ip-country': 'CA' }))).toBe('CA');
+    expect(getCountryFromRequestHeaders(headersOf({ 'cf-ipcountry': 'fr' }))).toBe('FR');
+    expect(
+      getCountryFromRequestHeaders(
+        headersOf({ 'x-vercel-ip-country': 'DE', 'cf-ipcountry': 'US' }),
+      ),
+    ).toBe('DE');
+    expect(getCountryFromRequestHeaders(headersOf({ 'cloudfront-viewer-country': 'JP' }))).toBe(
+      'JP',
+    );
+    expect(getCountryFromRequestHeaders(headersOf({ 'x-country-code': 'BR' }))).toBe('BR');
+  });
+
+  it('rejects unknown-country sentinels and malformed values', () => {
+    expect(getCountryFromRequestHeaders(headersOf({ 'cf-ipcountry': 'XX' }))).toBeNull();
+    expect(getCountryFromRequestHeaders(headersOf({ 'cf-ipcountry': 'T1' }))).toBeNull();
+    expect(getCountryFromRequestHeaders(headersOf({ 'x-country-code': 'USA' }))).toBeNull();
+    expect(getCountryFromRequestHeaders(headersOf({}))).toBeNull();
+  });
+});
+
+describe('resolveDetectedLocale', () => {
+  const base = {
+    acceptLanguage: 'fr-CA, en;q=0.5',
+    countryCode: 'DE',
+    availableCodes: ['en', 'fr', 'de'],
+    defaultCode: 'en',
+  };
+
+  it('browser mode uses Accept-Language', () => {
+    expect(resolveDetectedLocale({ ...base, mode: 'browser' })).toBe('fr');
+  });
+
+  it('country mode uses the geo country', () => {
+    expect(resolveDetectedLocale({ ...base, mode: 'country' })).toBe('de');
+  });
+
+  it('browser_then_country prefers the browser and falls back to country', () => {
+    expect(resolveDetectedLocale({ ...base, mode: 'browser_then_country' })).toBe('fr');
+    expect(
+      resolveDetectedLocale({
+        ...base,
+        mode: 'browser_then_country',
+        acceptLanguage: 'ja',
+      }),
+    ).toBe('de');
+  });
+
+  it('default mode ignores all signals', () => {
+    expect(resolveDetectedLocale({ ...base, mode: 'default' })).toBe('en');
+  });
+
+  it('always falls back to the default language when detection finds nothing', () => {
+    expect(
+      resolveDetectedLocale({
+        mode: 'browser_then_country',
+        acceptLanguage: 'ja',
+        countryCode: 'JP',
+        availableCodes: ['en', 'fr'],
+        defaultCode: 'fr',
+      }),
+    ).toBe('fr');
+    expect(
+      resolveDetectedLocale({
+        mode: 'country',
+        acceptLanguage: null,
+        countryCode: null,
+        availableCodes: ['en'],
+        defaultCode: 'en',
+      }),
+    ).toBe('en');
+  });
+});

package/templates/nextblock-template/lib/i18n/detection.ts

@@ -0,0 +1,192 @@
+// Pure language-detection helpers shared by proxy.ts (edge), app/layout.tsx and
+// the CMS languages settings. Keep this module free of server-only / next/*
+// imports so the proxy can use it.
+import { COUNTRY_PRIMARY_LANGUAGES } from './country-languages';
+
+/** site_settings key holding the detection config (non-sensitive, anon-readable). */
+export const LANGUAGE_DETECTION_SETTING_KEY = 'language_detection_settings';
+
+/** next/cache tag for the layout's cached read of the detection settings. */
+export const LANGUAGE_DETECTION_CACHE_TAG = 'public-language-detection';
+
+export const LANGUAGE_DETECTION_MODES = [
+  'browser',
+  'country',
+  'browser_then_country',
+  'default',
+] as const;
+
+export type LanguageDetectionMode = (typeof LANGUAGE_DETECTION_MODES)[number];
+
+export interface LanguageDetectionSettings {
+  /** How the first language served to a new visitor is chosen. */
+  mode: LanguageDetectionMode;
+  /** true = persist the visitor's language for a year; false = session-only cookie. */
+  rememberVisitorChoice: boolean;
+}
+
+// "browser" matches the long-standing page-level Accept-Language fallback, so an
+// absent row keeps today's intended behavior.
+export const DEFAULT_LANGUAGE_DETECTION_SETTINGS: LanguageDetectionSettings = {
+  mode: 'browser',
+  rememberVisitorChoice: true,
+};
+
+/** Coerce an arbitrary site_settings jsonb value into valid settings. */
+export function normalizeLanguageDetectionSettings(value: unknown): LanguageDetectionSettings {
+  const fallback = DEFAULT_LANGUAGE_DETECTION_SETTINGS;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ...fallback };
+  }
+  const record = value as Record<string, unknown>;
+  const mode = LANGUAGE_DETECTION_MODES.includes(record.mode as LanguageDetectionMode)
+    ? (record.mode as LanguageDetectionMode)
+    : fallback.mode;
+  const rememberVisitorChoice =
+    typeof record.rememberVisitorChoice === 'boolean'
+      ? record.rememberVisitorChoice
+      : fallback.rememberVisitorChoice;
+  return { mode, rememberVisitorChoice };
+}
+
+export interface AcceptLanguageEntry {
+  /** Full lowercased tag, e.g. "fr-ca". */
+  tag: string;
+  /** Base language, e.g. "fr". */
+  base: string;
+  quality: number;
+}
+
+/** Parse an Accept-Language header into tags sorted by q-value (wildcards and q=0 dropped). */
+export function parseAcceptLanguage(header: string | null | undefined): AcceptLanguageEntry[] {
+  if (!header) return [];
+  const entries: AcceptLanguageEntry[] = [];
+  for (const part of header.split(',')) {
+    const [rawTag, ...params] = part.trim().split(';');
+    const tag = rawTag?.trim().toLowerCase();
+    if (!tag || tag === '*' || !/^[a-z]{1,8}(-[a-z0-9]{1,8})*$/.test(tag)) continue;
+    let quality = 1;
+    for (const param of params) {
+      const eq = param.indexOf('=');
+      if (eq === -1) continue;
+      if (param.slice(0, eq).trim() !== 'q') continue;
+      const parsed = Number(param.slice(eq + 1).trim());
+      if (!Number.isNaN(parsed)) quality = Math.min(Math.max(parsed, 0), 1);
+    }
+    if (quality <= 0) continue;
+    entries.push({ tag, base: tag.split('-')[0] as string, quality });
+  }
+  // Stable sort: q descending, original order preserved among equals.
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => b.entry.quality - a.entry.quality || a.index - b.index)
+    .map(({ entry }) => entry);
+}
+
+/**
+ * Match ordered candidate tags against the site's language codes.
+ * Candidate priority wins: for each candidate (in order) try, exact tag
+ * ("fr-ca" = "fr-CA"), then candidate base to site code ("fr-CA" -> "fr"),
+ * then candidate base to site code base ("fr" -> "fr-CA") — so a visitor's
+ * top language matched loosely beats a lower preference matched exactly.
+ * Returns the site code as configured (original casing) or null.
+ */
+export function matchLocale(candidates: string[], availableCodes: string[]): string | null {
+  if (candidates.length === 0 || availableCodes.length === 0) return null;
+  const available = availableCodes.map((code) => ({
+    code,
+    lower: code.toLowerCase(),
+    base: code.toLowerCase().split('-')[0] as string,
+  }));
+
+  for (const candidate of candidates) {
+    const tag = candidate.toLowerCase();
+    const base = tag.split('-')[0] as string;
+    const match =
+      available.find((lang) => lang.lower === tag) ??
+      available.find((lang) => lang.lower === base) ??
+      available.find((lang) => lang.base === base);
+    if (match) return match.code;
+  }
+  return null;
+}
+
+// Geo country headers injected by the popular hosts/CDNs, in precedence order.
+const COUNTRY_HEADER_NAMES = [
+  'x-vercel-ip-country', // Vercel
+  'cf-ipcountry', // Cloudflare
+  'cloudfront-viewer-country', // AWS CloudFront
+  'x-country-code', // generic reverse proxies
+] as const;
+
+/** Read the visitor's ISO 3166-1 alpha-2 country from host geo headers, if any. */
+export function getCountryFromRequestHeaders(headers: {
+  get(name: string): string | null;
+}): string | null {
+  for (const name of COUNTRY_HEADER_NAMES) {
+    const value = headers.get(name)?.trim().toUpperCase();
+    // Cloudflare uses XX/T1 for unknown/Tor; only accept real alpha-2 codes.
+    if (value && /^[A-Z]{2}$/.test(value) && value !== 'XX' && value !== 'T1') {
+      return value;
+    }
+  }
+  return null;
+}
+
+export function detectLocaleFromBrowser(
+  acceptLanguage: string | null | undefined,
+  availableCodes: string[],
+): string | null {
+  return matchLocale(
+    parseAcceptLanguage(acceptLanguage).map((entry) => entry.tag),
+    availableCodes,
+  );
+}
+
+export function detectLocaleFromCountry(
+  countryCode: string | null | undefined,
+  availableCodes: string[],
+): string | null {
+  if (!countryCode) return null;
+  const candidates = COUNTRY_PRIMARY_LANGUAGES[countryCode.toUpperCase()];
+  if (!candidates || candidates.length === 0) return null;
+  return matchLocale(candidates, availableCodes);
+}
+
+export interface ResolveDetectedLocaleInput {
+  mode: LanguageDetectionMode;
+  acceptLanguage: string | null | undefined;
+  countryCode: string | null | undefined;
+  availableCodes: string[];
+  defaultCode: string;
+}
+
+/**
+ * Pick the first language for a visitor with no (valid) language cookie.
+ * Always falls back to the site's default language when detection finds no match.
+ */
+export function resolveDetectedLocale({
+  mode,
+  acceptLanguage,
+  countryCode,
+  availableCodes,
+  defaultCode,
+}: ResolveDetectedLocaleInput): string {
+  let detected: string | null = null;
+  switch (mode) {
+    case 'browser':
+      detected = detectLocaleFromBrowser(acceptLanguage, availableCodes);
+      break;
+    case 'country':
+      detected = detectLocaleFromCountry(countryCode, availableCodes);
+      break;
+    case 'browser_then_country':
+      detected =
+        detectLocaleFromBrowser(acceptLanguage, availableCodes) ??
+        detectLocaleFromCountry(countryCode, availableCodes);
+      break;
+    case 'default':
+      break;
+  }
+  return detected ?? defaultCode;
+}

package/templates/nextblock-template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextblock-cms/template",
-  "version": "0.12.14",
+  "version": "0.12.15",
   "private": true,
   "scripts": {
     "dev": "next dev",

package/templates/nextblock-template/proxy.ts

@@ -3,13 +3,24 @@ import { NextResponse, type NextRequest } from 'next/server';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import type { Database } from '@nextblock-cms/db';
 import { resolveSupabaseAnonKey, resolveSupabaseUrl } from './lib/setup/env-status';
+import {
+  LANGUAGE_DETECTION_SETTING_KEY,
+  DEFAULT_LANGUAGE_DETECTION_SETTINGS,
+  getCountryFromRequestHeaders,
+  normalizeLanguageDetectionSettings,
+  resolveDetectedLocale,
+  type LanguageDetectionSettings,
+} from './lib/i18n/detection';
 
 type Profile = Database['public']['Tables']['profiles']['Row'];
 type UserRole = Database['public']['Enums']['user_role'];
 
 const LANGUAGE_COOKIE_KEY = 'NEXT_USER_LOCALE';
+// Fallbacks used only when the languages table can't be read (unprovisioned
+// instance, transient DB error). The live language list comes from the DB.
 const DEFAULT_LOCALE = 'en';
-const SUPPORTED_LOCALES = ['en', 'fr'];
+const FALLBACK_LOCALES = ['en', 'fr'];
+const LANGUAGE_COOKIE_MAX_AGE_SECONDS = 31_536_000;
 const cacheLoggingEnabled = process.env.NEXTBLOCK_CACHE_LOGGING_ENABLED === 'true';
 
 const cmsRoutePermissions: Record<string, UserRole[]> = {
@@ -138,6 +149,88 @@ async function hasProvisionedAdmin(supabase: SupabaseClient): Promise<boolean> {
   }
 }
 
+interface LocaleRuntimeConfig {
+  /** Active language codes as configured in the CMS (is_active null counts as active). */
+  activeCodes: string[];
+  /** The is_default language, falling back to the first active language. */
+  defaultCode: string;
+  detection: LanguageDetectionSettings;
+}
+
+// Module-level cache for the language list + detection settings, mirroring
+// provisionedAdminCache: middleware modules persist across requests in a worker,
+// so this keeps locale resolution to at most one DB round-trip per minute.
+let localeConfigCache: { value: LocaleRuntimeConfig | null; expires: number } | null = null;
+// In-flight load shared by concurrent cache misses so a burst of requests right
+// after expiry (or on a cold isolate) collapses to a single DB round-trip.
+let localeConfigInflight: Promise<LocaleRuntimeConfig | null> | null = null;
+
+async function loadLocaleRuntimeConfig(
+  supabase: SupabaseClient,
+): Promise<LocaleRuntimeConfig | null> {
+  const now = Date.now();
+  try {
+    const [languagesResult, detectionResult] = await Promise.all([
+      supabase.from('languages').select('code, is_default, is_active'),
+      supabase
+        .from('site_settings')
+        .select('value')
+        .eq('key', LANGUAGE_DETECTION_SETTING_KEY)
+        .maybeSingle(),
+    ]);
+
+    const activeLanguages = (languagesResult.data ?? []).filter(
+      (language: { is_active: boolean | null }) => language.is_active !== false,
+    );
+    if (languagesResult.error || activeLanguages.length === 0) {
+      localeConfigCache = { value: null, expires: now + 10_000 };
+      return null;
+    }
+
+    const defaultCode =
+      activeLanguages.find((language: { is_default: boolean }) => language.is_default)?.code ??
+      activeLanguages[0].code;
+    // A missing/failed settings row means "use defaults" — detection must not
+    // break just because the setting was never saved.
+    const detection = detectionResult.error
+      ? { ...DEFAULT_LANGUAGE_DETECTION_SETTINGS }
+      : normalizeLanguageDetectionSettings(detectionResult.data?.value);
+
+    const value: LocaleRuntimeConfig = {
+      activeCodes: activeLanguages.map((language: { code: string }) => language.code),
+      defaultCode,
+      detection,
+    };
+    localeConfigCache = { value, expires: now + 60_000 };
+    return value;
+  } catch {
+    localeConfigCache = { value: null, expires: now + 10_000 };
+    return null;
+  }
+}
+
+/**
+ * Loads the active languages and the admin-configured detection settings
+ * (site_settings.language_detection_settings — non-sensitive, anon-readable).
+ * Returns null when the DB can't answer (unprovisioned/transient error); the
+ * caller then falls back to the legacy hardcoded locale behavior. Results (and
+ * failures) are cached briefly so an outage never adds per-request queries, and
+ * concurrent misses share one in-flight load.
+ */
+function getLocaleRuntimeConfig(
+  supabase: SupabaseClient,
+): Promise<LocaleRuntimeConfig | null> {
+  if (localeConfigCache && localeConfigCache.expires > Date.now()) {
+    return Promise.resolve(localeConfigCache.value);
+  }
+  if (!localeConfigInflight) {
+    localeConfigInflight = loadLocaleRuntimeConfig(supabase).finally(() => {
+      localeConfigInflight = null;
+    });
+  }
+  return localeConfigInflight;
+}
+
 function getHttpOrigin(value: string | undefined): string | null {
   if (!value) {
     return null;
@@ -414,11 +507,35 @@ export async function proxy(request: NextRequest) {
 
   await supabase.auth.getSession();
 
+  // Locale resolution needs nothing from the authenticated user, so load the
+  // locale config concurrently with the user lookup instead of serially.
   const cookieLocale = request.cookies.get(LANGUAGE_COOKIE_KEY)?.value;
-  let currentLocale = cookieLocale;
-
-  if (!currentLocale || !SUPPORTED_LOCALES.includes(currentLocale)) {
-    currentLocale = DEFAULT_LOCALE;
+  const [localeConfig, userResult] = await Promise.all([
+    getLocaleRuntimeConfig(supabase),
+    supabase.auth.getUser(),
+  ]);
+
+  let currentLocale: string;
+  let rememberVisitorChoice = DEFAULT_LANGUAGE_DETECTION_SETTINGS.rememberVisitorChoice;
+
+  if (localeConfig) {
+    rememberVisitorChoice = localeConfig.detection.rememberVisitorChoice;
+    if (cookieLocale && localeConfig.activeCodes.includes(cookieLocale)) {
+      // An explicit or previously detected choice always wins over detection.
+      currentLocale = cookieLocale;
+    } else {
+      currentLocale = resolveDetectedLocale({
+        mode: localeConfig.detection.mode,
+        acceptLanguage: request.headers.get('accept-language'),
+        countryCode: getCountryFromRequestHeaders(request.headers),
+        availableCodes: localeConfig.activeCodes,
+        defaultCode: localeConfig.defaultCode,
+      });
+    }
+  } else {
+    // Languages unreadable (unprovisioned / transient error): legacy behavior.
+    currentLocale =
+      cookieLocale && FALLBACK_LOCALES.includes(cookieLocale) ? cookieLocale : DEFAULT_LOCALE;
   }
 
   requestHeaders.set('X-User-Locale', currentLocale);
@@ -426,7 +543,7 @@ export async function proxy(request: NextRequest) {
   const {
     data: { user },
     error: userError,
-  } = await supabase.auth.getUser();
+  } = userResult;
 
   // First-boot setup gate (configured but no admin yet, and nobody signed in): funnel
   // anonymous traffic to /setup so the wizard can create the first admin. A logged-in
@@ -518,10 +635,26 @@ export async function proxy(request: NextRequest) {
     finalResponse.cookies.set(cookie.name, cookie.value, cookie);
   });
 
-  if (request.cookies.get(LANGUAGE_COOKIE_KEY)?.value !== currentLocale) {
+  // Only persist the locale cookie when we actually resolved it against the DB.
+  // If localeConfig is null (unprovisioned / transient DB error) we still stamp
+  // X-User-Locale for rendering, but writing the fallback would clobber a
+  // returning visitor's valid non-fallback cookie (e.g. 'es') with 'en' for a
+  // year — so a transient outage must never overwrite a stored preference.
+  const requestCookieLocale = request.cookies.get(LANGUAGE_COOKIE_KEY)?.value;
+  // Re-issue when the value changed OR whenever "remember" is off: the request
+  // Cookie header carries no expiry, so rewriting a same-value session cookie is
+  // the only way to downgrade a previously persistent cookie after an admin
+  // turns remembering off (without it, old 1-year cookies would linger).
+  if (
+    localeConfig &&
+    (requestCookieLocale !== currentLocale || !rememberVisitorChoice)
+  ) {
+    // "Remember visitor's choice" ON -> persist for a year; OFF -> session cookie,
+    // so detection runs again on the next browser session while the language still
+    // sticks for the current one (switcher + in-session consistency).
     finalResponse.cookies.set(LANGUAGE_COOKIE_KEY, currentLocale, {
       path: '/',
-      maxAge: 31_536_000,
+      ...(rememberVisitorChoice ? { maxAge: LANGUAGE_COOKIE_MAX_AGE_SECONDS } : {}),
       sameSite: 'lax',
     });
   }