`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

// 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

// 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:

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.

2.5 KiB Raw Blame History

augmentation — ContributedTranslationKeys registration