Next Intl Messages and Formatting

Use this skill when the task is about message authoring, translation consumption, or locale-aware formatting behavior.

Scope

• message catalog structure and namespace strategy
• ICU authoring patterns
• useTranslations, t.rich, t.markup, t.raw, t.has
• useFormatter and named formats
• typed ICU arguments and message validation
• useExtracted as an optional workflow

Routing cues

• message JSON structure, namespace design, ICU, rich text, formatting, validation -> use this skill
• defineRouting, locale switchers, domains, pathnames -> use next-intl-routing-and-navigation
• getTranslations in metadata, setRequestLocale, testing, error files -> use next-intl-server-runtime
• plugin flags, TypeScript augmentation, Crowdin, loading strategy -> use next-intl-workflows-and-tooling

Workflow

1. Read references/icu-rich-text-and-catalogs.md first.
2. If the task touches formats, validation, or extracted messages, read references/formatting-validation-and-types.md.
3. Keep namespaces close to the component boundary and choose the lowest stable common branch.
4. Move language logic into ICU messages instead of branching in application code.

Guardrails

• Keep catalogs as nested objects. Do not use . inside message keys.
• Prefer consuming translations from components. Use server awaitables only for the official server-side exceptions.
• Do not call useTranslations or useFormatter in async components.
• Use t.rich(...) for translatable markup. Avoid surrounding sentence fragments with hardcoded JSX.
• Use t.markup(...) when tags should compile to strings, not React nodes.
• Use format.list(...) for locale-aware lists instead of joining strings manually.
• Treat useExtracted as experimental, not as the default baseline.

Canonical APIs

• useTranslations
• useFormatter
• t.rich
• t.markup
• t.raw
• t.has

Maintenance

• Snapshot date: 2026-03-10
• Package snapshot: next-intl@4.8.3 published 2026-02-16

References

• references/icu-rich-text-and-catalogs.md
• references/formatting-validation-and-types.md