ehoandClaude Sonnet 5
e7156c5132
Restructures into apps/ssp + apps/behandelportal (two Angular projects) plus libs/shared + libs/beheer (cross-app libraries), replacing WP-61's separate sibling repo. That split had already produced real drift: a hand-vendored copy of the backend's OpenAPI doc, a shared/ui+layout tree forked and silently diverging (7 files), and beheer + the styles.scss token bridge duplicated byte-for-byte across both repos. - git mv the SSP's src/app/* into apps/ssp/; fold shared/, beheer/, environments/, the Storybook docs/*.mdx, and styles.scss into libs/shared + libs/beheer (all confirmed identical between the two repos before merging). auth stays deliberately duplicated per ADR-0002 (actor-specific, expected to diverge) - amended there. - One generated API client (libs/shared), no more vendored swagger.json. - .dependency-cruiser split into a base factory + one config per app, and Storybook into .storybook-ssp/.storybook-behandelportal - both forced by the @auth/* alias resolving to different directories per app. - SiteHeaderComponent/ShellComponent gained HEADER_NAV_ITEMS/ HEADER_ADMIN_LINKS/DEBUG_PANEL injection tokens so each app supplies its own nav/admin-links/dev-panel instead of one being hardcoded. - CLAUDE.md, ARCHITECTURE.md, dependencies.md, and ADR-0002 updated; WP-67 backlog entry documents the full decision trail. npm run ci green (lint, dep:check x2, 360 tests across ssp/ behandelportal/shared/beheer, both localized builds, backend tests, snippet + api-client drift); both dev servers, both Storybook instances, and docker compose verified working. The old sibling repo (/home/eho/repos/behandelportal) is left untouched, not deleted. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
94 lines
4.2 KiB
Plaintext
94 lines
4.2 KiB
Plaintext
import { Meta } from '@storybook/addon-docs/blocks';
|
|
|
|
<Meta title="Foundations/Internationalization" />
|
|
|
|
# Internationalization (the locale seam)
|
|
|
|
Every user-visible string goes through Angular's first-party **`$localize`** — no
|
|
third-party i18n library. The source locale is **`nl`**; a second locale is a
|
|
**translation file, not a code change**. That's the seam: adding English touched
|
|
`src/locale/messages.en.xlf`, not the components.
|
|
|
|
## How it's wired
|
|
|
|
| Piece | Where | What |
|
|
| -------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
|
|
| Source locale | `angular.json` → `i18n.sourceLocale` | `nl` — the language the code is written in |
|
|
| Locales | `angular.json` → `i18n.locales.en` | points at `src/locale/messages.en.xlf` |
|
|
| Missing-translation policy | `angular.json` → `i18nMissingTranslation` | `error` — a missing `<target>` fails the build |
|
|
| Runtime global | `angular.json` → `polyfills` | `@angular/localize/init` provides `$localize` |
|
|
| English build/serve | `angular.json` → `configurations.en` | `ng build --configuration=en`, `ng serve --configuration=en` |
|
|
|
|
Locale switching is **build-time**, not runtime: each locale is its own bundle. There is
|
|
no in-app language picker (out of scope for the POC).
|
|
|
|
## Authoring copy
|
|
|
|
Two forms, same custom-id rule. The id is **stable** and shaped `@@<context>.<key>`, so
|
|
translations survive copy edits.
|
|
|
|
**In TS logic / value objects — tagged template:**
|
|
|
|
```ts
|
|
// src/app/registratie/domain/value-objects/postcode.ts
|
|
return err($localize`:@@validation.postcode:Voer een geldige postcode in, bijv. 1234 AB.`);
|
|
```
|
|
|
|
With placeholders (named, so translators can reorder):
|
|
|
|
```ts
|
|
$localize`:@@aanvraag.row.ingediend:ingediend op ${formatDatumNl(a.submittedAt)}:datum:`;
|
|
```
|
|
|
|
**In inline component templates — the `i18n` attribute:**
|
|
|
|
```html
|
|
<!-- src/app/auth/ui/login-form/login-form.component.ts -->
|
|
<app-button type="submit" i18n="@@login.submit">Inloggen met DigiD</app-button>
|
|
```
|
|
|
|
**Shared/English components never hardcode Dutch.** They expose copy as `input()`s with
|
|
localizable defaults; the domain caller may override. See
|
|
`shared/ui/async/async.component.ts`:
|
|
|
|
```ts
|
|
errorText = input($localize`:@@async.error:Er ging iets mis bij het laden van de gegevens.`);
|
|
```
|
|
|
|
## Extract & translate loop
|
|
|
|
```bash
|
|
npm run extract-i18n # ng extract-i18n → src/locale/messages.xlf (source, nl)
|
|
```
|
|
|
|
Then a translator fills `<target>`s in `src/locale/messages.en.xlf`. Both files carry the
|
|
same trans-units (currently 690 = 690, no drift); the `.en.xlf` header is
|
|
`source-language="nl" target-language="en"`. Because `i18nMissingTranslation: error`, a
|
|
forgotten target breaks the `en` build rather than silently shipping Dutch.
|
|
|
|
## Testing languages without coupling to the strings
|
|
|
|
**Rule: never assert on rendered copy.** Copy is the thing that changes per locale and per
|
|
edit — a test that reads `"Voer een geldige postcode in"` breaks the moment a translator or
|
|
a product owner touches the wording, in every locale. Assert on what's _invariant_ instead:
|
|
|
|
- **Parsers / value objects** — assert on the `Result` discriminant and the parsed value,
|
|
not the error message. This is the existing house pattern
|
|
(`registratie/domain/value-objects/postcode.spec.ts`):
|
|
|
|
```ts
|
|
expect(parsePostcode('0234AB').ok).toBe(false); // rejects — never inspects the $localize string
|
|
```
|
|
|
|
- **The seam itself** — if you must verify that translation works, check that a known
|
|
**id flips**, not that a specific phrase appears. Build/serve the `en` configuration and
|
|
confirm the target for a stable id renders, e.g. `login.submit`: `nl` "Inloggen met
|
|
DigiD" → `en` "Log in with DigiD". You're testing the wiring, not the wording.
|
|
|
|
```bash
|
|
ng serve --configuration=en # then eyeball, or point an e2e at the en bundle
|
|
```
|
|
|
|
See [Testing strategy](?path=/docs/foundations-testing-strategy--docs) for how this fits the
|
|
rest of the test pyramid.
|