Type-check message calls

Generate and include declarations that check source strings, contexts, and message values while you edit.

A message call can be valid TypeScript yet request the wrong catalog entry. A changed context or misspelled placeholder can leave source text or {name} on screen. Extraction generates declarations that make the known source messages part of the application's type system.

Generate the declaration and include it #

With the CLI installed, run:

sh
npx lingo extract --src src --source-locale en

The default outputs are locales/en.jsonc and lingo.d.ts. Add lingo.d.ts to the application's existing tsconfig include list if no current pattern includes it. Preserve the other entries:

json
{
  "include": ["src", "lingo.d.ts"]
}

Run the application's normal typecheck. A declaration outside the compiler's project does not constrain any calls. If extraction uses --types or i18n.typesPath, include that actual output path instead.

What the generated interface means #

The file augments LingoMessages with source strings and their options. This illustrates the generated shape:

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

Regenerate this file rather than maintaining the illustration by hand. The greeting now requires values.name and its extracted context. Save accepts either recorded context. An unlisted source fails the MessageKey constraint.

Without generated entries, LingoMessages is empty and MessageKey permits any string. Once populated, MessageKey becomes the union of its string keys. The runtime behavior is unchanged: these are editing-time constraints on l.text and l.rich.

Keep types current with the source #

Re-extract after changing text, context, or placeholders. Removed messages become orphans and are excluded from generation. Entries without context contribute no generated signature unless another active entry for the same source provides context. Multiple contexts for the same source form a union.

To check freshness without writing files:

sh
npx lingo extract --src src --source-locale en --check

This compares both JSONC and declarations with current extraction. It is a local check, not a translation request. Run it alongside the typecheck so an old declaration cannot silently define yesterday's message inventory.

Value types and coverage #

The generator recognizes top-level ICU arguments. It uses number for plural, ordinal, and number arguments; string for select arguments; Date | number for date/time arguments; and string | number for simple placeholders. It does not discover every placeholder nested inside a plural branch, so test those branch values explicitly.

Generated source constraints apply to text and rich. The plural and select helpers retain their own forms/options signatures. Rich calls add an optional tags map, but the declarations do not verify the target's tag placement.

Types tell you whether a call matches the extracted source contract. Rendering tests tell you whether the loaded translation can use those values. Keep both: a valid call can still receive an absent catalog entry or malformed target ICU.