missing translation key error in production next-intl build

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