# `augmentation` — `ContributedTranslationKeys` registration

## Purpose

Side-effect-only TypeScript module that augments
`@suaveplan/react-i18n`'s `ContributedTranslationKeys` interface with
every key shipped by the `@suaveplan/react-ui` chassis. 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/index.ts` so consumers' `tsconfig` picks it
up automatically when they `import "@suaveplan/react-ui"`.

## Features

- Module augmentation that registers every chassis translation key
  into the branded `TranslationKey` union
- Side-effect-only — zero runtime cost
- Mirror of the canonical `en-GB.json` source-of-truth bundle so
  consumer autocomplete in IDEs lists the chassis keys without
  manually importing or copying them

## Usage: Basic example

```ts
// In a consumer app:
import "@suaveplan/react-ui";
import { useTranslation } from "@suaveplan/react-i18n";

function Toolbar() {
    const { t } = useTranslation();
    return <button>{t("react-ui.themeToggle.label")}</button>; // typechecks
}
```

## Usage: Advanced example

```ts
// Compile-time error path:
import "@suaveplan/react-ui";

const key = "react-ui.dialog.cloze"; // typo; not in ContributedTranslationKeys
t(key); // Type error: argument of type '"react-ui.dialog.cloze"' is not
        // assignable to parameter of type 'TranslationKey'
```

## API Reference

This file exposes no runtime values. Its sole effect is to extend the
TypeScript type space:

```ts
declare module "@suaveplan/react-i18n" {
    interface ContributedTranslationKeys {
        readonly "react-ui.themeToggle.label": true;
        // … one entry per key in en-GB.json
    }
}
```

After the augmentation lands, `TranslationKey` (defined in
`@suaveplan/react-i18n` as `string & { ... } & (keyof AppTranslationKeys
| keyof ContributedTranslationKeys)`) accepts the chassis keys as legal
literal values.

## Implementation notes

The file is hand-edited in this version to mirror the canonical
`en-GB.json` exactly. A future generator
(`scripts/generate-translation-types.ts` from `@suaveplan/react-i18n`)
will rewrite this file from the JSON whenever keys change so the type
augmentation never drifts from runtime catalog contents. The empty
`export {}` at the end is required so TypeScript treats the file as a
module (not a script) — without it, the `declare module` block would
be parsed in script mode and silently merged into the global scope.