From 92f825242a31ae7987f695dfd0b78404997ab8c3 Mon Sep 17 00:00:00 2001
From: Edwin van den Houdt <eho@respellion.nl>
Date: Thu, 23 Jul 2026 17:21:55 +0200
Subject: [PATCH] feat(i18n): CIBG "Taal instellen" language switcher
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a language switcher matching the CIBG Taal-instellen pattern: a <nav> region
(sr-only heading + aria-label) with an endonym link per locale (lang/hreflang, the
active one aria-current + non-link), mounted right after the skip link in the shell.
Compile-time $localize means each locale is its own bundle under /<locale>/, so the
switch is a full navigation to the sibling bundle — active locale read from the baked
base href. Pure localeLinks() (+spec) builds path-preserving targets. Since `ng serve`
serves nl-only at /, add `npm run serve:i18n` (localized build + a tiny static server
with per-locale SPA fallback) so the switch is demoable. +story.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package.json                                  |  1 +
 scripts/serve-i18n.mjs                        | 53 ++++++++++++
 .../language-switcher.component.ts            | 82 +++++++++++++++++++
 .../language-switcher.stories.ts              | 15 ++++
 .../language-switcher/locale-links.spec.ts    | 27 ++++++
 .../layout/language-switcher/locale-links.ts  | 37 +++++++++
 .../shared/layout/shell/shell.component.ts    | 10 ++-
 src/locale/messages.en.xlf                    |  8 ++
 src/locale/messages.xlf                       | 28 +++++--
 9 files changed, 253 insertions(+), 8 deletions(-)
 create mode 100644 scripts/serve-i18n.mjs
 create mode 100644 src/app/shared/layout/language-switcher/language-switcher.component.ts
 create mode 100644 src/app/shared/layout/language-switcher/language-switcher.stories.ts
 create mode 100644 src/app/shared/layout/language-switcher/locale-links.spec.ts
 create mode 100644 src/app/shared/layout/language-switcher/locale-links.ts

diff --git a/package.json b/package.json
index 00a5415..620bde4 100644
--- a/package.json
+++ b/package.json
@@ -20,6 +20,7 @@
     "dep:check": "depcruise src/app --config .dependency-cruiser.js",
     "dep:graph": "bash scripts/dep-graph.sh",
     "gen:snippets": "node scripts/gen-snippets.mjs",
+    "serve:i18n": "ng build --localize && node scripts/serve-i18n.mjs",
     "ci": "bash scripts/ci-local.sh",
     "e2e": "playwright test",
     "extract-i18n": "ng extract-i18n --output-path src/locale"
diff --git a/scripts/serve-i18n.mjs b/scripts/serve-i18n.mjs
new file mode 100644
index 0000000..ef64761
--- /dev/null
+++ b/scripts/serve-i18n.mjs
@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Serve the localized production build so the language switcher actually works locally.
+// `ng build --localize` emits dist/.../browser/{nl,en}/ (each with base href /nl/ or /en/).
+// Plain `ng serve` (npm start) serves only nl at /, so switching 404s there — this static
+// server serves both locale subdirs with per-locale SPA fallback (a miss under /<locale>/…
+// serves that locale's index.html), so deep-link switches resolve. Demo only, not prod infra.
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { join, extname, normalize } from 'node:path';
+
+const ROOT = 'dist/atomic-design-poc/browser';
+const PORT = 4300;
+const MIME = {
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.mjs': 'text/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+  '.png': 'image/png',
+};
+
+const send = (res, status, body, type) => {
+  res.writeHead(status, { 'content-type': type });
+  res.end(body);
+};
+
+createServer(async (req, res) => {
+  const url = decodeURIComponent((req.url ?? '/').split('?')[0]);
+  // Landing at / has no locale bundle — redirect to Dutch.
+  if (url === '/') {
+    res.writeHead(302, { location: '/nl/' });
+    return res.end();
+  }
+  const rel = normalize(url).replace(/^(\.\.[/\\])+/, ''); // no path traversal
+  const locale = url.startsWith('/en/') ? 'en' : 'nl';
+  try {
+    const file = await readFile(join(ROOT, rel));
+    send(res, 200, file, MIME[extname(rel)] ?? 'application/octet-stream');
+  } catch {
+    // SPA fallback to the requested locale's index.html.
+    try {
+      const index = await readFile(join(ROOT, locale, 'index.html'));
+      send(res, 200, index, 'text/html');
+    } catch {
+      send(res, 404, 'Not found', 'text/plain');
+    }
+  }
+}).listen(PORT, () => {
+  console.log(`Serving ${ROOT} at http://localhost:${PORT}/  (→ /nl/, /en/)`);
+});
diff --git a/src/app/shared/layout/language-switcher/language-switcher.component.ts b/src/app/shared/layout/language-switcher/language-switcher.component.ts
new file mode 100644
index 0000000..7c32947
--- /dev/null
+++ b/src/app/shared/layout/language-switcher/language-switcher.component.ts
@@ -0,0 +1,82 @@
+import { Component, computed, input } from '@angular/core';
+import { Locale, localeLinks } from './locale-links';
+
+// CIBG-GAP EXTENSION: "Taal instellen" (designsystem.cibg.nl/componenten/taal-instellen) — no
+// vendored Huisstijl class ships for it, so this is a small hand-rolled surface built from the
+// token bridge. See cibg-gaps.mdx.
+/**
+ * Organism: CIBG "Taal instellen" language switcher. A `<nav>` region (screenreader heading +
+ * aria-label) with one link per locale — the endonym, tagged with its `lang`/`hreflang`, the
+ * active one marked `aria-current` and rendered as text (not a link).
+ *
+ * Compile-time $localize means each locale is a separate bundle under `/<locale>/`, so switching
+ * is a plain full-page navigation to the sibling bundle (not a runtime toggle). The active locale
+ * is read from the baked `<base href>` (`/en/` → en, else nl) — the deployment truth, independent
+ * of the app-config `LOCALE_ID`. Only functional where both locale bundles are served (the
+ * localized build, e.g. `npm run serve:i18n`), not under plain `ng serve` (nl-only at `/`).
+ */
+@Component({
+  selector: 'app-language-switcher',
+  styles: [
+    `
+      nav {
+        display: flex;
+        justify-content: flex-end;
+        gap: var(--rhc-space-max-md);
+        padding: var(--rhc-space-max-sm) var(--rhc-space-max-2xl);
+        font-size: var(--rhc-text-font-size-sm);
+      }
+      a {
+        color: var(--rhc-color-hemelblauw-700);
+      }
+      [aria-current] {
+        font-weight: var(--rhc-text-font-weight-semi-bold);
+      }
+      .sr-only {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        margin: -1px;
+        padding: 0;
+        overflow: hidden;
+        clip: rect(0 0 0 0);
+        white-space: nowrap;
+        border: 0;
+      }
+    `,
+  ],
+  template: `
+    <nav [attr.aria-label]="navLabel">
+      <h2 class="sr-only">{{ heading }}</h2>
+      @for (l of links(); track l.locale) {
+        @if (l.active) {
+          <span [attr.lang]="l.locale" aria-current="true">{{ l.label }}</span>
+        } @else {
+          <a [attr.lang]="l.locale" [attr.hreflang]="l.locale" [href]="l.href">{{ l.label }}</a>
+        }
+      }
+    </nav>
+  `,
+})
+export class LanguageSwitcherComponent {
+  /** Override the detected locale (stories/tests); the app detects it from the base href. */
+  activeLocale = input<Locale | undefined>(undefined);
+
+  private readonly detected: Locale = /\/en\//.test(document.baseURI) ? 'en' : 'nl';
+  private readonly loc =
+    typeof location !== 'undefined'
+      ? location
+      : ({ pathname: '/', search: '', hash: '' } as Location);
+
+  protected links = computed(() =>
+    localeLinks(
+      this.loc.pathname,
+      this.activeLocale() ?? this.detected,
+      this.loc.search,
+      this.loc.hash,
+    ),
+  );
+
+  protected navLabel = $localize`:@@lang.navLabel:Taal / Language`;
+  protected heading = $localize`:@@lang.heading:Kies een taal`;
+}
diff --git a/src/app/shared/layout/language-switcher/language-switcher.stories.ts b/src/app/shared/layout/language-switcher/language-switcher.stories.ts
new file mode 100644
index 0000000..24bdf6f
--- /dev/null
+++ b/src/app/shared/layout/language-switcher/language-switcher.stories.ts
@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/angular';
+import { LanguageSwitcherComponent } from './language-switcher.component';
+
+const meta: Meta<LanguageSwitcherComponent> = {
+  title: 'Design System/Organisms/Language Switcher',
+  component: LanguageSwitcherComponent,
+};
+export default meta;
+type Story = StoryObj<LanguageSwitcherComponent>;
+
+/** Dutch active (the source locale). */
+export const NederlandsActive: Story = { args: { activeLocale: 'nl' } };
+
+/** English active. */
+export const EnglishActive: Story = { args: { activeLocale: 'en' } };
diff --git a/src/app/shared/layout/language-switcher/locale-links.spec.ts b/src/app/shared/layout/language-switcher/locale-links.spec.ts
new file mode 100644
index 0000000..903f838
--- /dev/null
+++ b/src/app/shared/layout/language-switcher/locale-links.spec.ts
@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { localeLinks } from './locale-links';
+
+describe('localeLinks', () => {
+  it('preserves the route when already under a locale prefix, marks the active one', () => {
+    const links = localeLinks('/nl/dashboard', 'nl');
+    expect(links.map((l) => [l.locale, l.href, l.active])).toEqual([
+      ['nl', '/nl/dashboard', true],
+      ['en', '/en/dashboard', false],
+    ]);
+  });
+
+  it('swaps the prefix and keeps a deep path (en active)', () => {
+    const links = localeLinks('/en/beheer/audit', 'en');
+    expect(links.find((l) => l.locale === 'nl')!.href).toBe('/nl/beheer/audit');
+    expect(links.find((l) => l.locale === 'en')!.active).toBe(true);
+  });
+
+  it('handles an unprefixed dev path (served at /), keeps query + hash', () => {
+    const links = localeLinks('/registreren', 'nl', '?scenario=slow', '#top');
+    expect(links.find((l) => l.locale === 'en')!.href).toBe('/en/registreren?scenario=slow#top');
+  });
+
+  it('a bare locale root maps to the sibling root', () => {
+    expect(localeLinks('/nl', 'nl').find((l) => l.locale === 'en')!.href).toBe('/en/');
+  });
+});
diff --git a/src/app/shared/layout/language-switcher/locale-links.ts b/src/app/shared/layout/language-switcher/locale-links.ts
new file mode 100644
index 0000000..1eb68bd
--- /dev/null
+++ b/src/app/shared/layout/language-switcher/locale-links.ts
@@ -0,0 +1,37 @@
+/** The app's two locales (Angular $localize: source `nl` + translation `en`). */
+export type Locale = 'nl' | 'en';
+
+export interface LocaleLink {
+  readonly locale: Locale;
+  /** Endonym — each language named in its own language (CIBG "Taal instellen"), not a code. */
+  readonly label: string;
+  /** Absolute path into the other locale's bundle, preserving the current route. */
+  readonly href: string;
+  readonly active: boolean;
+}
+
+const LOCALES: readonly { locale: Locale; label: string }[] = [
+  { locale: 'nl', label: 'Nederlands' },
+  { locale: 'en', label: 'English' },
+];
+
+/**
+ * Build the two language links for the switcher. Compile-time i18n serves each locale as its
+ * own bundle under `/<locale>/`, so switching is a full navigation to the sibling bundle at the
+ * same route. Strips any leading `/nl` or `/en` from the current path and re-prefixes the target
+ * locale, keeping query + hash. Pure — no DOM (the component passes `location.*` in).
+ */
+export function localeLinks(
+  pathname: string,
+  active: Locale,
+  search = '',
+  hash = '',
+): LocaleLink[] {
+  const rest = pathname.replace(/^\/(nl|en)(?=\/|$)/, '') || '/';
+  return LOCALES.map(({ locale, label }) => ({
+    locale,
+    label,
+    href: `/${locale}${rest}${search}${hash}`,
+    active: locale === active,
+  }));
+}
diff --git a/src/app/shared/layout/shell/shell.component.ts b/src/app/shared/layout/shell/shell.component.ts
index 969cdf0..23b480b 100644
--- a/src/app/shared/layout/shell/shell.component.ts
+++ b/src/app/shared/layout/shell/shell.component.ts
@@ -3,12 +3,19 @@ import { RouterOutlet } from '@angular/router';
 import { SiteHeaderComponent } from '@shared/layout/site-header/site-header.component';
 import { SiteFooterComponent } from '@shared/layout/site-footer/site-footer.component';
 import { DebugStateComponent } from '@shared/ui/debug-state/debug-state.component';
+import { LanguageSwitcherComponent } from '@shared/layout/language-switcher/language-switcher.component';
 
 /** Template: persistent app chrome. Header + footer mount once; only the routed
     content inside <router-outlet> changes (and cross-fades — see styles.scss). */
 @Component({
   selector: 'app-shell',
-  imports: [RouterOutlet, SiteHeaderComponent, SiteFooterComponent, DebugStateComponent],
+  imports: [
+    RouterOutlet,
+    SiteHeaderComponent,
+    SiteFooterComponent,
+    DebugStateComponent,
+    LanguageSwitcherComponent,
+  ],
   styles: [
     `
       :host {
@@ -46,6 +53,7 @@ import { DebugStateComponent } from '@shared/ui/debug-state/debug-state.componen
   ],
   template: `
     <a href="#main" class="skip" i18n="@@shell.skipLink">Naar de inhoud</a>
+    <app-language-switcher />
     <div class="layout">
       <app-site-header />
       <main id="main" class="main">
diff --git a/src/locale/messages.en.xlf b/src/locale/messages.en.xlf
index 9f95fff..670de8f 100644
--- a/src/locale/messages.en.xlf
+++ b/src/locale/messages.en.xlf
@@ -2234,6 +2234,14 @@
           <context context-type="linenumber">48,49</context>
         </context-group>
       </trans-unit>
+      <trans-unit id="lang.navLabel" datatype="html">
+        <source>Taal / Language</source>
+        <target datatype="html">Taal / Language</target>
+      </trans-unit>
+      <trans-unit id="lang.heading" datatype="html">
+        <source>Kies een taal</source>
+        <target datatype="html">Choose a language</target>
+      </trans-unit>
       <trans-unit id="footer.tagline" datatype="html">
         <source>De Rijksoverheid. Voor Nederland.</source>
         <target datatype="html">The Government of the Netherlands.</target>
diff --git a/src/locale/messages.xlf b/src/locale/messages.xlf
index 92aa16e..96b318b 100644
--- a/src/locale/messages.xlf
+++ b/src/locale/messages.xlf
@@ -891,42 +891,42 @@
         <source>Alleen-lezen weergave. De behandelaar stelt de brief op.</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/brief/ui/letter-composer/letter-composer.component.ts</context>
-          <context context-type="linenumber">177</context>
+          <context context-type="linenumber">175</context>
         </context-group>
       </trans-unit>
       <trans-unit id="brief.status.draft" datatype="html">
         <source>Concept</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/brief/ui/letter-composer/letter-composer.component.ts</context>
-          <context context-type="linenumber">187</context>
+          <context context-type="linenumber">185</context>
         </context-group>
       </trans-unit>
       <trans-unit id="brief.status.submitted" datatype="html">
         <source>Ter beoordeling</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/brief/ui/letter-composer/letter-composer.component.ts</context>
-          <context context-type="linenumber">189</context>
+          <context context-type="linenumber">187</context>
         </context-group>
       </trans-unit>
       <trans-unit id="brief.status.approved" datatype="html">
         <source>Goedgekeurd</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/brief/ui/letter-composer/letter-composer.component.ts</context>
-          <context context-type="linenumber">191</context>
+          <context context-type="linenumber">189</context>
         </context-group>
       </trans-unit>
       <trans-unit id="brief.status.rejected" datatype="html">
         <source>Afgewezen</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/brief/ui/letter-composer/letter-composer.component.ts</context>
-          <context context-type="linenumber">193</context>
+          <context context-type="linenumber">191</context>
         </context-group>
       </trans-unit>
       <trans-unit id="brief.status.sent" datatype="html">
         <source>Verzonden</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/brief/ui/letter-composer/letter-composer.component.ts</context>
-          <context context-type="linenumber">195</context>
+          <context context-type="linenumber">193</context>
         </context-group>
       </trans-unit>
       <trans-unit id="brief.section.required" datatype="html">
@@ -2838,6 +2838,20 @@
           <context context-type="linenumber">28,29</context>
         </context-group>
       </trans-unit>
+      <trans-unit id="lang.navLabel" datatype="html">
+        <source>Taal / Language</source>
+        <context-group purpose="location">
+          <context context-type="sourcefile">src/app/shared/layout/language-switcher/language-switcher.component.ts</context>
+          <context context-type="linenumber">72</context>
+        </context-group>
+      </trans-unit>
+      <trans-unit id="lang.heading" datatype="html">
+        <source>Kies een taal</source>
+        <context-group purpose="location">
+          <context context-type="sourcefile">src/app/shared/layout/language-switcher/language-switcher.component.ts</context>
+          <context context-type="linenumber">73</context>
+        </context-group>
+      </trans-unit>
       <trans-unit id="pageShell.backLabel" datatype="html">
         <source>Terug naar overzicht</source>
         <context-group purpose="location">
@@ -2849,7 +2863,7 @@
         <source>Naar de inhoud</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/shared/layout/shell/shell.component.ts</context>
-          <context context-type="linenumber">48,49</context>
+          <context context-type="linenumber">55,56</context>
         </context-group>
       </trans-unit>
       <trans-unit id="footer.tagline" datatype="html">