Troubleshoot React messages

Find where a message loses its translation, values, tags, or locale between extraction and rendering.

Follow the message that is actually on screen. Its source and context select a key; the nearest provider supplies the catalog; the selected template is formatted with the call's values. Inspecting those inputs usually locates the failure without changing generated keys by hand.

useLingo throws outside a provider #

Put LingoProvider above the component that calls the hook, including in tests and isolated previews. A provider returned by the same component is below that hook. Move the hook into a child, or use createLingo(locale, messages) in a function that does not render through React context.

Use React 19 for the current provider implementation. Its React 19 context shorthand is not made compatible with React 18 by the package's broader peer range.

Source text appears instead of a translation #

  1. Inspect the nearest provider's actual locale and messages. Messages must be a hash-to-string map, not a file URL, promise, or LocaleFile.
  2. Compute computeKey(source, context) from the exact call. Look for that key in the supplied map. Punctuation, whitespace, and context changes can create a new identity.
  3. If extraction lacks the key, use a literal source and context with a supported receiver such as l.text(...), then run extraction again. A computed call can render at runtime without being extractable.
  4. If the source catalog has the key but the target does not, retrieve the completed translation and reload the map. Submission alone does not place the file in the application.
  5. If the file has the key but the provider does not, inspect the loader's paths and route selection. Catalog loading shows the source-key join required when translated JSONC has lost metadata.

Missing and empty-string values both use source fallback. Development warnings distinguish the two and are deduplicated by key and locale. Production suppresses these diagnostics, so an empty console is not a catalog-completeness check.

The Next loader returns {} for a missing file but can throw for malformed JSONC. TanStack's built-in catalog catches missing, loading, and parsing failures as {} and caches that result. In either case, source fallback can keep the page readable while hiding a loading problem.

A placeholder or ICU expression remains visible #

Check the values object reaching the call. Missing simple values leave {name} visible. With no values object, the runtime returns the selected template without formatting.

For a complex ICU message, inspect the selected target's syntax, argument names, and value types. A parse or format error returns that same template and emits a deduplicated development error. It may therefore display a malformed translation, rather than the English source. Repair the template or supply the missing argument, then render the case again.

Generated declarations catch detected source arguments, but they neither validate target syntax nor discover every placeholder nested inside an ICU branch. Exercise the affected branch with real values.

Rich messages use named callbacks such as tags.link. Match the translated tag name exactly and keep its destination in the callback. Unknown paired and self-closing tags, and unclosed opening tags, remain literal text.

Use distinct names for nested elements. Repeated same-name nesting is outside the parser's supported structure. Rich messages support simple placeholders rather than full ICU grammar; use the text grammar helpers for that work. Rich text shows the supported forms.

The URL changes but the language does not #

Replace locale and catalog together. A locale-only update can format French text with Spanish rules. Also check nested providers: a different-locale child is independent and does not inherit the parent's catalog.

Follow the selected adapter's switcher. Next Pages uses router navigation and a locale cookie. TanStack uses plain anchors so a new request can load the new catalog.

Text, direction, or dates change during hydration #

Compare the server and client inputs: catalog revision, locale, values, timestamp, timezone, and relative-time reference. Set document lang and dir in the framework shell; the base provider does not change them. Then test the initial HTML and the hydrated page using the server-rendering checklist.