# `augmentation` — `ContributedTranslationKeys` registration

## Purpose

Side-effect-only TypeScript module that augments
`@suaveplan/react-i18n`'s `ContributedTranslationKeys` interface with
every key shipped by `@suaveplan/react-forms`. The augmentation runs
purely in TypeScript's type space — there is no runtime value to
import — but the file is included as a side-effect import from
`src/locales/locales.ts` so consumers' `tsconfig` picks up the
declaration when they `import "@suaveplan/react-forms"`.

The augmentation widens the branded `TranslationKey` union so a
recipe's `next` button label is statically known to be a registered
key. Misuse (`labels: { next: "typo" }`) is a TypeScript error before
the form ever mounts.

## Features

- Pure type-space augmentation — zero bytes of JavaScript runtime cost.
- Mirrors the keys in the generated `augmentation.d.ts` exactly so
  side-effect import paths and declaration paths stay consistent.
- Imported as a side effect from `src/locales/locales.ts` so the
  package barrel carries the augmentation transitively.
- Empty runtime export keeps tooling that strips type-only files from
  side-effect chains honest.

## Usage: Basic Example

The augmentation is automatically applied when the package is imported.
No explicit usage is required.

```ts
import "@suaveplan/react-forms";
import type { TranslationKey } from "@suaveplan/react-i18n";

const k: TranslationKey = "react-forms.wizard.next"; // ✅ typechecks
```

## Usage: Advanced Example

If the consumer is building a server-side helper that does not import
the package barrel but still wants the augmentation widened, pull the
augmentation alone:

```ts
import "@suaveplan/react-forms/locales/augmentation";
import type { TranslationKey } from "@suaveplan/react-i18n";

declare const fromConfig: string;
const key = fromConfig as TranslationKey;
```

## API Reference

This module exports a single empty object literal (`export {}`) so the
TypeScript compiler treats it as a module and applies the
`declare module` augmentation. There are no runtime exports.

## Implementation Notes

- The file MUST stay in sync with `augmentation.d.ts`; both are
  generated from `en-GB.json` by `bun
  packages/react/react-i18n/scripts/generate-translation-types.ts
  packages/react/react-forms --package-name @suaveplan/react-forms`.
- Two files exist (one `.ts`, one `.d.ts`) so consumers' bundlers do
  not strip the runtime side-effect even when declaration-only files
  are filtered out by aggressive tree-shaking.
- The unique-symbol brand on `ContributedTranslationKeys` ensures the
  augmentation surface stays mergeable across packages — never declare
  a `type ContributedTranslationKeys = { ... }`; it MUST stay an
  `interface`.