Migrate existing React messages
Move a small React message fixture to explicit source-and-context messages without losing placeholders, plural behavior, or accepted translations.
An existing React catalog already contains useful decisions: lookup identities, interpolation rules, plural behavior, and translations someone has reviewed. Moving to source-and-context messages should preserve that work. Convert one complete component first, map its accepted translations to the new identities, and compare what it renders before expanding the migration.
Capture the old behavior before changing identity #
Choose a component with a label, variable, link, count, and conditional message. Save its old keys, source and target wording, interpolation syntax, namespace, and provider locale. Render it in the source and one target language with fixed values. This gives the migration a concrete result to preserve.
For example, an existing i18next-style call might be:
t("account.greeting", { name });Its source catalog might contain Welcome, {{name}}. Do not copy that interpolation syntax unchanged into a new message contract. The explicit React message uses a named {name} variable:
l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});The delimiter change shown here is specific to that source-library configuration. Check the installed library before converting other messages: custom interpolation delimiters and plural conventions can require different changes.
Map message behavior, not only method names #
Use text for plain messages with values, rich for named component slots, plural for count-dependent forms, and select for exact-value alternatives with an other fallback. Rich interactive messages supplies a complete example of all four.
An old rich-message component may encode links by index. Replace those indices with meaningful named slots and keep the link destination in code. Preserve variable names, types, and semantic roles. An old plural catalog may store suffix keys; the new runtime builds its plural message from forms. Verify the target language's behavior instead of renaming suffix keys mechanically.
Choose context that explains the message's use. The new identity derives from source wording and context rather than account.greeting. Keep a migration table with the old key, locale, extracted new key, and any syntax conversion. For the greeting, that row records the conversion from {{name}} to {name}. The mapping lets a reviewer follow accepted wording into the new catalog and see which messages remain unmapped.
Extract and import a small catalog deliberately #
Install @lingo.dev/react and configure LingoProvider through the React quickstart. Use React 19 for the current provider implementation; its declared React 18 peer range is not a substitute for testing an older application. After converting the component, run the installed CLI:
lingo extract --src src --source-locale enWithout path overrides, inspect locales/en.jsonc and lingo.d.ts. Find each source message and context, then copy the actual extracted key into the migration table. Keeping the old key or inventing a hash would disconnect the target from the runtime lookup.
Place each accepted target under its mapped new key. Convert placeholder, rich-slot, and plural syntax deliberately while retaining meaning. Load a hash-to-string target map through the catalog-loading workflow, using the matching source's active keys when target metadata is absent. Keep unmapped entries visible as remaining work instead of classifying them as obsolete.
Supply the requested locale and its target messages together to LingoProvider. Keep the old and new providers around their respective callers during incremental migration. The provider contract explains same-locale merging and different-locale isolation; check these when migrating a nested screen.
Verify missing and malformed cases #
Render the fixture with the same values used before migration. Compare visible meaning, variable placement, link behavior, plural output, and fallback selection. Include zero, one, and larger counts; long variable values; and an unknown select value.
Remove a target entry in a local fixture and check the source fallback. Missing or empty messages can render source text, so a usable screen does not prove target coverage. Run extraction consistency checks and TypeScript checks with the generated declarations included, then run the application's existing rendering tests. Types establish call compatibility, not translation quality.
For a malformed rich tag or ICU message, inspect output and diagnostics. The new runtime can leave literal markup or an unformatted template visible, so compare this behavior with the application's requirements before removing the old runtime. React troubleshooting documents those limits.
Use agent assistance as reviewed work #
Ask the agent to inspect the existing library, preserve a key mapping, identify unsupported patterns, and separate source edits from catalog import. Review its proposed source and catalog changes before applying them.
Expand by component or namespace after the fixture passes its rendering and native checks. Retain both catalogs until every caller and accepted target has a verified destination. Remove the old provider and dependency only when no remaining code uses them. API clients and router adapters have separate responsibilities; changing the message runtime does not replace them.