skills/docs/ui/forms/react-forms/src/locales/augmentation.md

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.

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:

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.