create-nextblock 0.12.14 → 0.12.16

package/templates/nextblock-template/app/cms/settings/languages/components/LanguageDetectionPanel.tsx

@@ -0,0 +1,188 @@
+'use client';
+
+import React, { useState, useTransition } from 'react';
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Checkbox,
+  RadioGroup,
+  RadioGroupItem,
+} from '@nextblock-cms/ui';
+import { toast } from 'react-hot-toast';
+import { Ban, Globe, Info, MapPin, Route } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import { updateLanguageDetectionSettings } from '../actions';
+import type {
+  LanguageDetectionMode,
+  LanguageDetectionSettings,
+} from '../../../../../lib/i18n/detection';
+
+interface ModeOption {
+  value: LanguageDetectionMode;
+  title: string;
+  description: string;
+  icon: LucideIcon;
+}
+
+const MODE_OPTIONS: ModeOption[] = [
+  {
+    value: 'browser',
+    title: 'Browser language',
+    description:
+      "Serve the language the visitor's browser prefers (Accept-Language header). Recommended — it reflects what each person actually reads.",
+    icon: Globe,
+  },
+  {
+    value: 'country',
+    title: "Visitor's country (IP)",
+    description:
+      'Serve the main language of the country the visitor browses from, using the geolocation headers provided by your host (Vercel, Cloudflare, CloudFront).',
+    icon: MapPin,
+  },
+  {
+    value: 'browser_then_country',
+    title: 'Browser language, then country',
+    description:
+      "Try the browser's preferred language first; when none of your languages match, fall back to the visitor's country.",
+    icon: Route,
+  },
+  {
+    value: 'default',
+    title: 'No detection',
+    description:
+      'Always serve the default language to new visitors. They can still switch manually with the language switcher (shown when more than one language is active).',
+    icon: Ban,
+  },
+];
+
+const COUNTRY_MODES: LanguageDetectionMode[] = ['country', 'browser_then_country'];
+
+export default function LanguageDetectionPanel({
+  initialSettings,
+  activeLanguageCount,
+}: {
+  initialSettings: LanguageDetectionSettings;
+  activeLanguageCount: number;
+}) {
+  const [mode, setMode] = useState<LanguageDetectionMode>(initialSettings.mode);
+  const [rememberVisitorChoice, setRememberVisitorChoice] = useState<boolean>(
+    initialSettings.rememberVisitorChoice,
+  );
+  const [savedSettings, setSavedSettings] = useState<LanguageDetectionSettings>(initialSettings);
+  const [isPending, startTransition] = useTransition();
+
+  // With fewer than two active languages every mode resolves to the same locale,
+  // so the whole panel is a no-op and the public language switcher is hidden.
+  const isMoot = activeLanguageCount < 2;
+
+  const isDirty =
+    mode !== savedSettings.mode || rememberVisitorChoice !== savedSettings.rememberVisitorChoice;
+
+  const handleSave = () => {
+    startTransition(async () => {
+      const result = await updateLanguageDetectionSettings({ mode, rememberVisitorChoice });
+      if (result?.error) {
+        toast.error(result.error);
+        return;
+      }
+      setSavedSettings({ mode, rememberVisitorChoice });
+      toast.success(result?.success ?? 'Language detection settings saved.');
+    });
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Language Detection</CardTitle>
+        <CardDescription>
+          How the site picks the first language for a new visitor. A language chosen with the
+          language switcher overrides detection for the rest of the visit — and for a year when
+          &ldquo;Remember the visitor&apos;s language&rdquo; is on. Changes reach new visitors
+          within about a minute.
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-6">
+        {isMoot && (
+          <p className="flex items-start gap-2 rounded-md border border-dashed p-3 text-sm text-muted-foreground">
+            <Info className="mt-0.5 h-4 w-4 shrink-0" />
+            <span>
+              Language detection takes effect once at least two active languages are configured.
+              With a single language every visitor receives that language and the public language
+              switcher is hidden — you can still choose a mode here so it applies as soon as you add
+              another language.
+            </span>
+          </p>
+        )}
+        <RadioGroup
+          value={mode}
+          onValueChange={(value) => setMode(value as LanguageDetectionMode)}
+          className="grid gap-3 md:grid-cols-2"
+        >
+          {MODE_OPTIONS.map((option) => (
+            <label
+              key={option.value}
+              className="flex cursor-pointer items-start gap-3 rounded-md border p-4 transition-colors has-[[data-state=checked]]:border-primary has-[[data-state=checked]]:bg-primary/5 has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-offset-2"
+            >
+              <RadioGroupItem
+                value={option.value}
+                className="mt-1"
+                aria-label={option.title}
+                aria-describedby={`detection-mode-desc-${option.value}`}
+              />
+              <span className="space-y-1">
+                <span className="flex items-center gap-2 text-sm font-medium">
+                  <option.icon className="h-4 w-4 text-muted-foreground" />
+                  {option.title}
+                </span>
+                <span
+                  id={`detection-mode-desc-${option.value}`}
+                  className="block text-sm text-muted-foreground"
+                >
+                  {option.description}
+                </span>
+              </span>
+            </label>
+          ))}
+        </RadioGroup>
+
+        <div aria-live="polite">
+          {COUNTRY_MODES.includes(mode) && (
+            <p className="rounded-md border border-dashed p-3 text-sm text-muted-foreground">
+              Country detection relies on the geolocation header your hosting platform adds to each
+              request (Vercel, Cloudflare, and CloudFront do this automatically). When the header is
+              missing, visitors get the default language
+              {mode === 'browser_then_country' ? ' unless their browser language matches' : ''}.
+            </p>
+          )}
+        </div>
+
+        <label className="flex cursor-pointer items-start gap-3">
+          <Checkbox
+            checked={rememberVisitorChoice}
+            onCheckedChange={(checked) => setRememberVisitorChoice(checked === true)}
+            className="mt-0.5"
+            aria-label="Remember the visitor's language"
+            aria-describedby="remember-visitor-desc"
+          />
+          <span className="space-y-1">
+            <span className="block text-sm font-medium">Remember the visitor&apos;s language</span>
+            <span id="remember-visitor-desc" className="block text-sm text-muted-foreground">
+              Keep the detected or chosen language in a cookie for a year. When off, the language
+              only sticks for the browsing session and is detected again on the next visit.
+            </span>
+          </span>
+        </label>
+      </CardContent>
+      <CardFooter className="justify-end">
+        <Button onClick={handleSave} disabled={!isDirty || isPending}>
+          {isPending ? 'Saving...' : 'Save Detection Settings'}
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+}

package/templates/nextblock-template/app/cms/settings/languages/page.tsx

@@ -23,6 +23,8 @@ import {
 } from "@nextblock-cms/ui";
 import type { Database } from "@nextblock-cms/db";
 import DeleteLanguageClientButton from './components/DeleteLanguageButton';
+import LanguageDetectionPanel from './components/LanguageDetectionPanel';
+import { getLanguageDetectionSettings } from './actions';
 
 type Language = Database['public']['Tables']['languages']['Row'];
 
@@ -41,7 +43,10 @@ async function getLanguages(): Promise<Language[]> {
 }
 
 export default async function CmsLanguagesListPage() {
-  const languages = await getLanguages();
+  const [languages, detectionSettings] = await Promise.all([
+    getLanguages(),
+    getLanguageDetectionSettings(),
+  ]);
   // The following line for searchParams will cause an error during static generation or if window is not defined.
   // It's better to pass searchParams as props if needed from the page component.
   // For this specific page, success messages are handled by redirect query params which Next.js makes available in page props.
@@ -144,6 +149,12 @@ export default async function CmsLanguagesListPage() {
           </Table>
         </div>
       )}
+      <div className="mt-6">
+        <LanguageDetectionPanel
+          initialSettings={detectionSettings}
+          activeLanguageCount={languages.filter((lang) => lang.is_active !== false).length}
+        />
+      </div>
       <div className="mt-6">
         <Alert variant="warning">
           <ShieldAlert className="h-4 w-4" />

package/templates/nextblock-template/app/layout.tsx

@@ -33,6 +33,13 @@ import {
   resolveSupabaseUrl,
 } from '../lib/setup/env-status';
 import { resolveMediaBaseUrl } from '../lib/storage/provider';
+import {
+  LANGUAGE_DETECTION_SETTING_KEY,
+  LANGUAGE_DETECTION_CACHE_TAG,
+  DEFAULT_LANGUAGE_DETECTION_SETTINGS,
+  normalizeLanguageDetectionSettings,
+  type LanguageDetectionSettings,
+} from '../lib/i18n/detection';
 
 const defaultUrl = process.env.NEXT_PUBLIC_URL || 'http://localhost:3000';
 
@@ -83,6 +90,25 @@ const getCachedLanguages = unstable_cache(
   { revalidate: PUBLIC_LAYOUT_REVALIDATE_SECONDS }
 );
 
+const getCachedLanguageDetectionSettings = unstable_cache(
+  async (): Promise<LanguageDetectionSettings> => {
+    const supabase = createStaticSupabaseClient();
+    const { data, error } = await supabase
+      .from('site_settings')
+      .select('value')
+      .eq('key', LANGUAGE_DETECTION_SETTING_KEY)
+      .maybeSingle();
+
+    // Absent row or read error = defaults (browser detection, remembered choice).
+    if (error) {
+      return { ...DEFAULT_LANGUAGE_DETECTION_SETTINGS };
+    }
+    return normalizeLanguageDetectionSettings(data?.value);
+  },
+  ['public-language-detection'],
+  { revalidate: PUBLIC_LAYOUT_REVALIDATE_SECONDS, tags: [LANGUAGE_DETECTION_CACHE_TAG] }
+);
+
 const getCachedCopyrightSettings = unstable_cache(
   async (): Promise<Record<string, string>> => {
     const supabase = createStaticSupabaseClient();
@@ -274,6 +300,7 @@ async function loadLayoutData() {
       globalCss: '',
       privacySettings: DEFAULT_PRIVACY_SETTINGS,
       footerAttributionEnabled: true,
+      rememberVisitorChoice: DEFAULT_LANGUAGE_DETECTION_SETTINGS.rememberVisitorChoice,
     };
   }
 
@@ -300,6 +327,7 @@ async function loadLayoutData() {
     translationsResult,
     isEcommerceActive,
     privacySettings,
+    languageDetectionSettings,
   ] = await Promise.all([
     supabase.auth.getUser(),
     getCachedLanguages().catch(() => getActiveLanguagesServerSide().catch(() => [])),
@@ -311,9 +339,19 @@ async function loadLayoutData() {
     getCachedTranslations().catch(() => []),
     verifyPackageOnline('ecommerce').catch(() => false),
     getPrivacySettings().catch(() => DEFAULT_PRIVACY_SETTINGS),
+    getCachedLanguageDetectionSettings().catch(() => ({
+      ...DEFAULT_LANGUAGE_DETECTION_SETTINGS,
+    })),
   ]);
 
-  const availableLanguages: Language[] = availableLanguagesResult;
+  // Serve only active languages, matching the proxy's detection set (is_active
+  // null counts as active). getCachedLanguages / getActiveLanguagesServerSide
+  // both return every row, so filtering here keeps the public switcher and
+  // LanguageProvider in step with the locales the proxy will actually honor —
+  // otherwise picking a deactivated language would ping-pong against the proxy.
+  const availableLanguages: Language[] = availableLanguagesResult.filter(
+    (lang) => lang.is_active !== false,
+  );
   const availableCurrencies: StoreCurrency[] = currenciesResult;
   const defaultLanguage: Language | null =
     availableLanguages.find((lang) => lang.is_default) ?? availableLanguages[0] ?? null;
@@ -368,6 +406,7 @@ async function loadLayoutData() {
     globalCss,
     privacySettings,
     footerAttributionEnabled,
+    rememberVisitorChoice: languageDetectionSettings.rememberVisitorChoice,
   };
 }
 
@@ -449,6 +488,7 @@ export default async function RootLayout({
     globalCss,
     privacySettings,
     footerAttributionEnabled,
+    rememberVisitorChoice,
   } = await loadLayoutData();
   const draft = await draftMode();
   // GTM container id comes solely from the privacy settings row (site_settings).
@@ -502,6 +542,7 @@ export default async function RootLayout({
           initialCurrencyCode={serverCurrencyCode}
           initialAvailableLanguages={availableLanguages}
           initialDefaultLanguage={defaultLanguage}
+          rememberVisitorChoice={rememberVisitorChoice}
           translations={translations}
           nonce={nonce}
         >

package/templates/nextblock-template/app/product/[slug]/page.tsx

@@ -111,8 +111,12 @@ export async function generateMetadata({ params }: ProductPageProps): Promise<Me
   if (!preferredLocale) {
     try {
       const hdrs = await headers();
-      const al = hdrs.get("accept-language");
-      if (al) preferredLocale = al.split(",")[0]?.split("-")[0];
+      // Proxy-detected locale first: it honors the CMS language-detection settings.
+      preferredLocale = hdrs.get("x-user-locale") || undefined;
+      if (!preferredLocale) {
+        const al = hdrs.get("accept-language");
+        if (al) preferredLocale = al.split(",")[0]?.split("-")[0];
+      }
     } catch {
       // ignore
     }
@@ -206,8 +210,12 @@ export default async function ProductPage({ params }: ProductPageProps) {
   if (!preferredLocale) {
     try {
       const hdrs = await headers();
-      const al = hdrs.get("accept-language");
-      if (al) preferredLocale = al.split(",")[0]?.split("-")[0];
+      // Proxy-detected locale first: it honors the CMS language-detection settings.
+      preferredLocale = hdrs.get("x-user-locale") || undefined;
+      if (!preferredLocale) {
+        const al = hdrs.get("accept-language");
+        if (al) preferredLocale = al.split(",")[0]?.split("-")[0];
+      }
     } catch {
       // ignore
     }

package/templates/nextblock-template/app/providers.tsx

@@ -44,6 +44,7 @@ export function Providers({ children, ...props }: { children: React.ReactNode;[k
     initialCurrencyCode,
     initialAvailableLanguages,
     initialDefaultLanguage,
+    rememberVisitorChoice,
     translations,
     nonce
   } = props;
@@ -54,6 +55,7 @@ export function Providers({ children, ...props }: { children: React.ReactNode;[k
         serverLocale={serverLocale}
         initialAvailableLanguages={initialAvailableLanguages}
         initialDefaultLanguage={initialDefaultLanguage}
+        rememberVisitorChoice={rememberVisitorChoice}
       >
         <CurrencyProvider
           initialCurrencies={initialCurrencies}

package/templates/nextblock-template/context/LanguageContext.tsx

@@ -27,13 +27,15 @@ interface LanguageProviderProps {
   serverLocale?: string; // Locale determined on the server (from X-User-Locale header)
   initialAvailableLanguages?: Language[]; // Languages fetched on the server
   initialDefaultLanguage?: Language | null; // Default language determined on the server
+  rememberVisitorChoice?: boolean; // CMS language-detection setting: persist locale for a year vs session-only
 }
 
 export const LanguageProvider = ({
   children,
   serverLocale,
   initialAvailableLanguages,
-  initialDefaultLanguage
+  initialDefaultLanguage,
+  rememberVisitorChoice = true
 }: LanguageProviderProps) => {
 
   const [currentLocale, _setCurrentLocale] = useState<string>(() => {
@@ -124,10 +126,18 @@ export const LanguageProvider = ({
       if (isMounted) { // Check mount status before final state updates
         _setCurrentLocale(effectiveLocale);
         if (typeof window !== 'undefined') {
-          localStorage.setItem(LANGUAGE_STORAGE_KEY, effectiveLocale);
+          // Mirror the cookie's persistence: when "remember" is off, keep no
+          // durable client-side record (and purge any left from a prior session)
+          // so the setting's "session only" promise holds on the client too.
+          if (rememberVisitorChoice) {
+            localStorage.setItem(LANGUAGE_STORAGE_KEY, effectiveLocale);
+          } else {
+            localStorage.removeItem(LANGUAGE_STORAGE_KEY);
+          }
           document.documentElement.lang = effectiveLocale;
         }
-        Cookies.set(LANGUAGE_COOKIE_KEY, effectiveLocale, { path: '/', expires: 365, sameSite: 'Lax' });
+        // Omitting `expires` makes it a session cookie, so detection re-runs next session.
+        Cookies.set(LANGUAGE_COOKIE_KEY, effectiveLocale, { path: '/', ...(rememberVisitorChoice ? { expires: 365 } : {}), sameSite: 'Lax' });
         setIsLoadingLanguages(false); // Done loading/initializing
       }
     };
@@ -137,7 +147,7 @@ export const LanguageProvider = ({
     return () => {
       isMounted = false; // Cleanup function to set isMounted to false
     };
-  }, [serverLocale, initialAvailableLanguages, initialDefaultLanguage, clientSelectedLocale]);
+  }, [serverLocale, initialAvailableLanguages, initialDefaultLanguage, clientSelectedLocale, rememberVisitorChoice]);
 
   const setCurrentLocaleCallback = useCallback(async (localeCode: string) => { // Add async here
     let localeToSet = DEFAULT_FALLBACK_LOCALE;
@@ -159,10 +169,15 @@ export const LanguageProvider = ({
 
     _setCurrentLocale(localeToSet);
     if (typeof window !== 'undefined') {
-      localStorage.setItem(LANGUAGE_STORAGE_KEY, localeToSet);
+      // Match the cookie's persistence (see the init effect): no durable record when off.
+      if (rememberVisitorChoice) {
+        localStorage.setItem(LANGUAGE_STORAGE_KEY, localeToSet);
+      } else {
+        localStorage.removeItem(LANGUAGE_STORAGE_KEY);
+      }
       document.documentElement.lang = localeToSet;
     }
-    Cookies.set(LANGUAGE_COOKIE_KEY, localeToSet, { path: '/', expires: 365, sameSite: 'Lax' });
+    Cookies.set(LANGUAGE_COOKIE_KEY, localeToSet, { path: '/', ...(rememberVisitorChoice ? { expires: 365 } : {}), sameSite: 'Lax' });
 
     // The LanguageSwitcher component is responsible for navigation (push or refresh).
     // We only set the clientSelectedLocale here to ensure the main useEffect
@@ -172,7 +187,7 @@ export const LanguageProvider = ({
       setClientSelectedLocale(localeToSet);
     }
     // router.refresh(); // REMOVED: LanguageSwitcher will handle navigation/refresh.
-  }, [availableLanguages]);
+  }, [availableLanguages, rememberVisitorChoice]);
 
   useEffect(() => {
     if (currentLocale && typeof window !== 'undefined') {

package/templates/nextblock-template/docs/TECHNICAL_SPECIFICATION.md

@@ -269,7 +269,7 @@ The following architectural invariants are enforced at workspace level and must
 
 **Editor Capabilities** — The `@nextblock-cms/editor` library (version `0.2.24`) exports `Editor`, `NotionEditor`, `EditorToolbar`, `EditorBubbleMenu`, `EditorFloatingMenu`, `EnhancedFloatingMenu`, `SlashCommandList`, `DragHandle`, `HtmlContent`, and `editorExtensions`. Feature set includes Tiptap StarterKit rich text, syntax-highlighted code blocks, tables, task lists, slash commands, drag handles, image handling, character counting, typography, mathematics, emoji, mentions, inline alert and call-to-action widgets, and custom HTML-preserving extensions for `div`, `style`, `script`, `svg`, `span`, and catch-all attribute preservation. A media-picker bridge is exposed via `setOpenImagePicker()`.
 
-**Translation & Localization** — The system supports two locales at present (`en`, `fr` — defined as `SUPPORTED_LOCALES` in `apps/nextblock/proxy.ts`), backed by `languages` and `translations` tables from migration `00000000000001_setup_cms_core.sql`. Content revision history is stored as snapshot + JSON Patch diff (enum `revision_type: snapshot, diff`) per migration `00000000000002_setup_content_tables.sql`.
+**Translation & Localization** — The set of served locales is the active rows of the `languages` table (managed at `/cms/settings/languages`; the proxy reads them with a 60-second in-memory cache and only falls back to the hardcoded `FALLBACK_LOCALES` `en`/`fr` when the DB is unreadable), backed by `languages` and `translations` tables from migration `00000000000001_setup_cms_core.sql`. First-visit language detection is admin-configurable (see F-007): browser `Accept-Language`, IP-country via host geo headers, combined, or always-default — implemented in `apps/nextblock/lib/i18n/detection.ts` and stored in `site_settings.language_detection_settings`. Content revision history is stored as snapshot + JSON Patch diff (enum `revision_type: snapshot, diff`) per migration `00000000000002_setup_content_tables.sql`.
 
 **Page Lifecycle** — Pages move through `draft`, `published`, and `archived` statuses (enum `page_status`).
 
@@ -619,7 +619,11 @@ Media management combines a Cloudflare R2-backed object store with an image-proc
 
 **Description**
 
-Two locales are currently supported — `en` and `fr` — defined as `SUPPORTED_LOCALES` in `apps/nextblock/proxy.ts` and seeded in migration `00000000000008_seed_platform_defaults.sql` (with `en` marked as the single default). The `languages` table enforces a single `is_default` row; the `translations` table stores translation keys with JSONB-per-locale values. Localized content entities (pages, posts, products) are clustered via `translation_group_id` UUIDs. Locale propagation uses the `NEXT_USER_LOCALE` cookie (`maxAge: 31_536_000` seconds, one year) and the `X-User-Locale` request header, both set by the request proxy. The client-side provider chain `LanguageProvider → TranslationsProvider` in `apps/nextblock/app/providers.tsx` bridges server-resolved locale into React context.
+Served locales are the active rows of the `languages` table, managed at `/cms/settings/languages` (the seed provides `en` and `fr`, with `en` as the single default; `apps/nextblock/proxy.ts` keeps `FALLBACK_LOCALES = ['en','fr']` only as a safety net when the DB is unreadable). The `languages` table enforces a single `is_default` row; the `translations` table stores translation keys with JSONB-per-locale values. Localized content entities (pages, posts, products) are clustered via `translation_group_id` UUIDs.
+
+**First-visit language detection** is admin-configurable on `/cms/settings/languages` and stored as the non-sensitive `site_settings` key `language_detection_settings` (`{ mode, rememberVisitorChoice }`). Modes: `browser` (default — full `Accept-Language` q-value parsing), `country` (visitor's country from host geo headers `x-vercel-ip-country` / `cf-ipcountry` / `cloudfront-viewer-country` / `x-country-code`, mapped through `apps/nextblock/lib/i18n/country-languages.ts`), `browser_then_country`, and `default` (no detection). The pure resolution helpers live in `apps/nextblock/lib/i18n/detection.ts`; the proxy applies them for any request without a valid locale cookie, resolving against the active languages + default language read from the DB with a 60-second in-memory cache.
+
+Locale propagation uses the `NEXT_USER_LOCALE` cookie and the `X-User-Locale` request header, both set by the request proxy. When `rememberVisitorChoice` is `true` (default) the cookie persists for one year (`maxAge: 31_536_000` seconds); when `false` it is a session cookie, so detection re-runs each new browser session (the client `LanguageProvider` mirrors the same expiry for manual switcher choices). A valid cookie always beats detection. The client-side provider chain `LanguageProvider → TranslationsProvider` in `apps/nextblock/app/providers.tsx` bridges server-resolved locale into React context.
 
 **Business Value:** Unlocks multi-market deployments without requiring adopters to integrate a separate i18n library. **User Benefits:** Language switching persists across sessions; same content IDs preserve relationships across translations. **Technical Context:** Implemented at schema level (migration `00000000000001_setup_cms_core.sql`), proxy level, and provider level.
 
@@ -1290,7 +1294,8 @@ This subsection provides the detailed, testable requirements that operationalize
 | F-005-RQ-002 | Editor MUST preserve custom HTML constructs (`div`, `style`, `script`, `svg`, `span`) and unrecognized attributes | Must-Have | High |
 | F-006-RQ-001 | Media uploads MUST record metadata (`object_key`, `file_type`, `size_bytes`, `width`, `height`, `blur_data_url`, `variants`) in the `media` table | Must-Have | Medium |
 | F-006-RQ-002 | `recordMediaUpload` MUST reject non-`ADMIN`/non-`WRITER` callers | Must-Have | Low |
-| F-007-RQ-001 | Locale MUST propagate via `NEXT_USER_LOCALE` cookie (1-year max age) and `X-User-Locale` header | Must-Have | Low |
+| F-007-RQ-001 | Locale MUST propagate via `NEXT_USER_LOCALE` cookie (1-year max age when `rememberVisitorChoice` is on; session cookie when off) and `X-User-Locale` header | Must-Have | Low |
+| F-007-RQ-002 | First-visit locale MUST honor the admin-configured detection mode (`browser`, `country`, `browser_then_country`, `default`) from `site_settings.language_detection_settings` | Must-Have | Medium |
 | F-008-RQ-001 | Content revisions MUST use the hybrid snapshot/diff model keyed by `revision_type` enum | Must-Have | Medium |
 | F-009-RQ-001 | Navigation items MUST support `HEADER`, `FOOTER`, `SIDEBAR` locations with hierarchy and ordering | Must-Have | Low |
 
@@ -1303,7 +1308,7 @@ This subsection provides the detailed, testable requirements that operationalize
 | F-004-RQ-001 | Block type string, content object | Validated block content or ZodError | Schema validation synchronous |
 | F-005-RQ-002 | HTML or Tiptap JSON | Rendered editor content preserving DOM | No HTML loss across round-trip |
 | F-006-RQ-001 | Multipart file or presigned PUT | `media` row with metadata | Upload completes within browser timeout |
-| F-007-RQ-001 | `lang` URL parameter or header | Locale cookie + `X-User-Locale` header | Proxy overhead < 5 ms |
+| F-007-RQ-001 | Locale cookie, `Accept-Language`, host geo-country header | Locale cookie + `X-User-Locale` header | Proxy overhead < 5 ms on cache hit; one Supabase round-trip per isolate per 60 s on miss (loaded concurrently with the auth lookup, shared across concurrent misses) |
 
 #### 2.2.1.3 Validation Rules — Content Delivery
 
@@ -1312,7 +1317,7 @@ This subsection provides the detailed, testable requirements that operationalize
 | F-001-RQ-002 | Image MIME must be in supported list | Only R2-served URLs accepted by next/image loader |
 | F-004-RQ-001 | Block `type` MUST exist in registry; content MUST pass Zod schema | Schema prevents XSS via typed fields |
 | F-006-RQ-001 | `size_bytes` must be non-negative; `object_key` unique | RLS: ADMIN/WRITER write; public read |
-| F-007-RQ-001 | Locale MUST be in `SUPPORTED_LOCALES` (`en`, `fr`) | Cookie uses default security attributes |
+| F-007-RQ-001 | Locale MUST be an active `languages` row (hardcoded `FALLBACK_LOCALES` `en`/`fr` only when the DB is unreadable) | Cookie uses default security attributes |
 | F-008-RQ-001 | Snapshot version MUST be unique per `page_id` | Writes RLS-restricted to ADMIN/WRITER |
 | F-009-RQ-001 | `menu_location` MUST be one of the three enum values | Writes RLS-restricted to ADMIN/WRITER |
 
@@ -1612,7 +1617,7 @@ The following matrix links features to the sections of the technical specificati
 | Build Status | `ecommerce:build` Nx standalone target currently not green (per §1.3.3.1) | F-013–F-022 |
 | Freemius Reconciliation | Webhook events acknowledged only; DB reconciliation pending (per §1.3.3.1) | F-017, F-021 |
 | Postal Code Shipping | Schema present; runtime resolver does not consume (per §1.3.3.1) | F-019 |
-| Locale Count | Only `en` and `fr` in current release (per §1.3.3.4) | F-007, F-009, F-013 |
+| Locale Count | Seed provides `en` and `fr`; additional locales are added as `languages` rows at `/cms/settings/languages` | F-007, F-009, F-013 |
 | Module Boundaries | `libs/ui` MUST NOT depend on `apps/nextblock` | F-028 |
 
 ### 2.4.2 Performance Requirements
@@ -1674,7 +1679,7 @@ The following matrix links features to the sections of the technical specificati
 | FX override | `FX_API_BASE_URL` toggle allows switching provider without code change | F-018 |
 | Sandbox dataset | `SANDBOX_RESET_SQL` in `/api/cron/reset-sandbox/route.ts` must be regenerated as schema evolves | F-025, F-026 |
 | Package alignment | `@nextblock-cms/ecom` package name vs. `@nextblock-cms/ecommerce` alias (per §1.3.3.1) requires coordination when republished | F-013–F-022 |
-| Locale expansion | Adding locales beyond `en`/`fr` requires updates to `SUPPORTED_LOCALES` and seed data | F-007 |
+| Locale expansion | Locales are DB-driven: add an active `languages` row (plus translations/content); `FALLBACK_LOCALES` in `proxy.ts` is only a DB-unreachable safety net | F-007 |
 | Block registry updates | New block types must satisfy F-024 contract and register in `blockRegistry.ts` | F-004, F-024 |
 | RLS policy review | Migration `00000000000006_setup_rls_and_grants.sql` should be audited on new table introduction | All DB-backed features |
 
@@ -2254,7 +2259,7 @@ The workspace implements a layered caching strategy aligned with the performance
 | `unstable_cache` (package activation) | 60 s | Avoids DB hit on every F-022 license check | `libs/db/src/lib/package-validation.ts` |
 | Next.js ISR (public layout) | 60 s (`PUBLIC_LAYOUT_REVALIDATE_SECONDS`) | Public content revalidation | `apps/nextblock/app/layout.tsx` |
 | Image cache TTL | 31,536,000 s (1 year) | Immutable optimized-image responses | `next.config.js` |
-| Locale cookie | 31,536,000 s (1 year) | Persistent locale preference | `proxy.ts` |
+| Locale cookie | 31,536,000 s (1 year), or session cookie when "remember visitor's language" is off | Persistent locale preference | `proxy.ts` |
 | On-demand revalidation | N/A | Per-path invalidation via `REVALIDATE_SECRET_TOKEN` | `/api/revalidate` (F-027) |
 | bfcache-compatible HTML | `max-age=0, must-revalidate` | Preserves back-forward cache | `proxy.ts` |
 
@@ -2615,9 +2620,9 @@ flowchart TB
     Supabase --> SyncSession[supabase.auth.getSession<br/>Sync Cookies]
     SyncSession --> Locale{Read<br/>NEXT_USER_LOCALE<br/>Cookie}
     
-    Locale -->|Valid: en or fr| SetLocaleHeader[Set X-User-Locale]
-    Locale -->|Invalid or Missing| DefaultEn[Default to 'en']
-    DefaultEn --> SetLocaleHeader
+    Locale -->|Valid: active language| SetLocaleHeader[Set X-User-Locale]
+    Locale -->|Invalid or Missing| Detect[Detect per settings:<br/>browser / country /<br/>browser_then_country / default]
+    Detect --> SetLocaleHeader
     
     SetLocaleHeader --> GetUser[supabase.auth.getUser]
     GetUser --> CmsGuard{Path starts<br/>with /cms?}