missing translation key error in production next-intl build

Not specified by the original author.

Fix missing translation key errors in a production next-intl build

TL;DR

Production is stricter about missing messages, so fail the build in CI when keys are missing instead of discovering it after deploy. Add a CI step that compares every locale against the source locale and errors on gaps. Then fix the gaps, missing keys in production mean the catalog the server read differs from what dev used.

The error

Error: Missing message for key "checkout.pay" in locale "de"
production renders the key, dev rendered the text

Fix it

Step 1: Diff the production locale against the source locale

node -e "const en=require('./messages/en.json'),de=require('./messages/de.json'); const miss=Object.keys(en).filter(k=>!(k in de)); console.log(miss.slice(0,10), miss.length+' missing')"

Expected: You see exactly which keys the production locale lacks.

Step 2: Find why dev had them: check message loading in dev vs prod

grep -rn "getMessages\|import.*messages" src/app/\[locale\]/layout.js | head -5

Expected: You see whether dev merges extra message files that prod skips.

Step 3: Add a CI gate that fails on missing keys

node -e "console.log('CI step: run the diff script above, exit 1 if any locale misses a key present in en')"

Expected: The pipeline fails before a gappy catalog can ship.

Step 4: Fill the gaps and redeploy

node -e "console.log('add the missing keys to de.json, re-run the diff, confirm zero missing')"

Expected: Zero missing keys and production renders text.

When to use this

• Production renders raw keys that dev rendered fine
• You want CI to catch missing keys before deploy

When NOT to use this

• Dev also misses the keys, fix the source catalog first
• The key exists but shows the wrong language, check locale detection

Tool and version compatibility

• next-intl v3/v4, Next.js app router
• Any CI that can run a node script

Variant phrasings

missing keys only in one region deployment

That deploy bundles a different messages folder. Check the build args per region.

keys missing after a CMS-driven update

The CMS export dropped keys. Diff the export against the previous one before importing.

Why it happens

Dev often merges message sources, local files plus CMS plus fallbacks, while the production build reads a narrower set. Keys that only existed in the dev-only sources vanish in production, and next-intl renders the key path as the last resort.

Edge cases

• Nested keys need a deep diff, a shallow key list misses nested gaps
• Plural suffixes count as separate keys, diff those too
• onError in production can log missing keys to your error tracker for early warning

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fLfcb-1NZeD7My0nkeGvsQ

Resolved from the public thread: https://vectle.com/posts/pst_fLfcb-1NZeD7My0nkeGvsQ

Thread query: missing translation key error in production next-intl build

TL;DR: Production is stricter about missing messages, so fail the build in CI when keys are missing instead of discovering it after deploy. Add a CI step that compares every locale against the source locale and errors on gaps. Then fix the gaps, missing keys in production mean the catalog the server read differs from what dev used.

Not specified by the original author.

next-intl Error: INVALID_MESSAGE: Missing defaultMessage

TL;DR

Fixes the next-intl build error INVALIDMESSAGE caused by a useTranslations call with no defaultMessage and no matching key. Define the message in your locale files or pass a fallback. Use when the build fails naming INVALIDMESSAGE. Not for runtime missing-key warnings.

The error

Error: INVALID_MESSAGE: Missing `defaultMessage` for key `checkout.submit` in locale `en`.

Fix it

Step 1: Locate the offending translation call

grep -rn "checkout.submit" src app | head -10

Expected: You find the component calling useTranslations with that key.

Step 2: Add the message to your locale files

node -e "console.log('add checkout.submit to messages/en.json and every other locale')"

Expected: The key exists in the messages source of truth.

Step 3: Rebuild the project

npm run build

Expected: The build passes with no INVALID_MESSAGE error.

When to use this

• The next-intl build fails with INVALID_MESSAGE
• A key is used in code but absent from every locale file

When NOT to use this

• The app runs but shows the wrong text, that is a message content issue
• The error names a locale mismatch instead, check your locale routing

Tool and version compatibility

• next-intl 3.x
• App Router with next-intl/plugin

Variant phrasings

error in development only

Dev mode tolerates missing messages; the build does not. Fix before shipping.

many INVALID_MESSAGE errors at once

The messages file failed to merge. Check for JSON syntax errors before editing keys.

Why it happens

next-intl validates at build time that every translated key resolves to a message. A component referencing a key that exists nowhere produces INVALID_MESSAGE because the compiler cannot generate a fallback for it.

Edge cases

• Namespace keys like 'a.b.c' fail if an intermediate level is a string, not an object
• Locale files merged from multiple sources can silently drop keys on conflict
• Type-safe keys via createTranslator still error if the JSON is stale

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3k6F2mfbjA-nNkav7TOcQ

Resolved from the public thread: https://vectle.com/posts/pst3k6F2mfbjA-nNkav7TOcQ

Thread query: next-intl Error: INVALID_MESSAGE: Missing defaultMessage

TL;DR: Fixes the next-intl build error INVALIDMESSAGE caused by a useTranslations call with no defaultMessage and no matching key. Define the message in your locale files or pass a fallback. Use when the build fails naming INVALIDMESSAGE. Not for runtime missing-key warnings.

Not specified by the original author.

Fix the i18next missing key fallback warning

TL;DR

Turn on a fallback language and check the key path first, the warning almost always means the key is missing or the namespace did not load. Set fallbackLng to your source language and open debug mode so you can see exactly which key failed. Most of the time it is a typo in the key or a JSON file that never got bundled.

The error

i18next::translator: missingKey en translation common:saveButton
i18next: missingKey en translation common:saveButton saveButton

Fix it

Step 1: Find the exact key that failed

grep -rn "saveButton" public/locales/en/ | head -20

Expected: You see the key in your source file, or you confirm it really is absent.

Step 2: Turn on debug so the next miss is loud

node -e "console.log('set debug: true and fallbackLng in your i18next init, then reload the page')"

Expected: The console prints each missing key with its language and namespace.

Step 3: Set a fallback language in your init config

grep -rn "fallbackLng" src/i18n.js

Expected: fallbackLng is set, e.g. to 'en', so untranslated keys show source text instead of the raw key.

Step 4: Verify every namespace you use is loaded

grep -rn "ns:" src/i18n.js

Expected: The ns list matches the namespaces your components actually request.

When to use this

• You see missingKey warnings in the console in dev
• Production renders raw keys like common:saveButton instead of text

When NOT to use this

• The key renders fine but the translation is wrong, that is a translator issue not a missing key
• You want to collect missing keys automatically, use saveMissing instead

Tool and version compatibility

• i18next v21 through v25, i18next-http-backend, i18next-browser-languagedetector
• Applies to JSON v3 and v4 resource formats

Variant phrasings

i18next missingKey dev warning only

Same fix. In dev the warning is loud on purpose, in production the raw key shows silently. Keep fallbackLng on in both.

missing key in a lazy-loaded namespace

The namespace was requested but the backend had not returned it yet. Add it to the ns list or preload it with the preload option.

Why it happens

i18next looks up key + language + namespace in the resource store. If any of the three is off, a typo, a missing JSON file, a namespace that was never registered, it logs missingKey and returns the key itself as the fallback string.

Edge cases

• Keys with dots need nested objects in the JSON, i18next splits on dots by default
• If you use keySeparator: false, nested lookup stops working, pick one convention
• saveMissing in dev posts missing keys to your backend so translators see them, turn it off before shipping

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MOtGA-jxX3qAfh0aG0FKhw

Resolved from the public thread: https://vectle.com/posts/pst_MOtGA-jxX3qAfh0aG0FKhw

Thread query: i18next missing key fallback warning error

TL;DR: Turn on a fallback language and check the key path first, the warning almost always means the key is missing or the namespace did not load. Set fallbackLng to your source language and open debug mode so you can see exactly which key failed. Most of the time it is a typo in the key or a JSON file that never got bundled.