On this page
- Why missing translations happen
- Catch missing translations at build time with i18next-cli
- Detect and handle missing translations at runtime
- Best practices for the i18next localization workflow
- Improve user experience when translations are missing
- Optimize i18next performance
- Frequently Asked Questions
- Conclusion
Missing translations in i18next are translation keys that exist in your source code but have no entry in your translation files, so users see raw keys like welcome_message instead of real text. The modern fix is two-layered: catch them at build time with i18next-cli (extract --ci + status) so they never reach production, and configure i18next at runtime (fallback languages, default values) so the few that slip through degrade gracefully. During development, saveMissing reports new keys to your translation backend.
- What is missing: a key used in code but absent from one or more translation files
- Symptom: users see the raw key (welcome.title) instead of translated text
- Build-time fix: i18next-cli extract adds keys automatically; status exits non-zero (failing CI) when locales are incomplete
- Runtime safeguards: fallbackLng, returnEmptyString: false, default values, saveMissing, custom missingKeyHandler
- Type safety: i18next-cli types generates TS definitions so mistyped keys fail to compile
- TMS workflow: saveMissing + Locize captures missing keys during development for translators to fill in
Why missing translations happen
In a typical i18next setup, translations are stored as JSON files (one per language and namespace), each containing key/value pairs. The t() function in your code looks up a key, finds the value for the active language, and renders it. A translation is "missing" when:
- The key is referenced in code but does not exist in any loaded translation file
- The key exists in your primary language file but not in a secondary language
- The namespace containing the key fails to load (404, CORS, wrong path)
- The key is misspelled in code or in the translation file
The default i18next behavior is to return the key itself as the rendered string. Users see welcome.title instead of "Welcome". This breaks the multilingual experience and damages trust, especially when it ships to production unnoticed.
The fix is layered: prevent missing keys at build time with static analysis (so they never reach production), and configure i18next's runtime fallbacks (so anything that slips through still renders something reasonable).
Catch missing translations at build time with i18next-cli
The most effective place to catch missing translations is before code ever runs. i18next-cli is the official static-analysis toolchain for the i18next ecosystem. It walks your source code, identifies every t() call, and keeps your translation files and types in sync. For a full walkthrough of the toolchain, see Supercharge Your i18next Workflow with the All-New i18next-cli; here we focus on the missing-translation parts.
Extract every key from your code
npx i18next-cli extractextract parses your source files (.ts, .tsx, .js, .jsx, and more via plugins), finds every t() call, and adds any missing keys to your JSON translation files automatically. Run it during development with --watch for instant feedback as you write new components:
npx i18next-cli extract --watchThis alone prevents the most common cause of missing translations: a developer adding a new t('feature.title') to code but forgetting to add the key to the translation files.
Gate CI on translation completeness
npx i18next-cli extract --ciIn CI/CD, extract --ci exits with a non-zero status code if extraction updates any translation file, for example because there is a new key in code that has not been added to the JSON. Add --dry-run to run the check without writing files. This blocks merges of code that would produce missing translations in production.
For a full health-check report:
npx i18next-cli statusstatus reports each locale's translation completeness, exiting non-zero when any locale is incomplete. In secondary languages, empty values count as missing; in the primary language, only keys used in code but absent from the files fail the check. Add --hide-translated to see only the gaps:
npx i18next-cli status de --hide-translatedBoth commands can run side-by-side in your pipeline: extract --ci catches "new keys not yet in files", status catches "files exist but values are blank".
Catch misspelled keys with TypeScript
npx i18next-cli typestypes reads your translation files and generates TypeScript definitions for every key. With strict mode enabled, calling t('nonexistent.key') becomes a compile error: typos are caught before code is even committed. Pair with extract to keep types and translations in lockstep.
Sync secondary languages
npx i18next-cli syncsync aligns secondary language files against your primary language: adds missing keys (with an empty value or your configured default), removes keys the primary no longer has. This catches the case where the German file lags behind the English (primary) file, or where a key was deleted from English but left behind in other languages. The primary language is the source of truth: a key added only to the German file is removed, not copied to English.
Detect and handle missing translations at runtime
Even with build-time gates, missing translations can still occur in production: a server-side rendering edge case, a dynamic key that was not statically analyzable, a translation file that fails to load over the network. i18next provides several runtime mechanisms to detect and handle these gracefully.
Enable debug mode in development
Set debug: true in your i18next config to log a missingKey message to the console whenever a key cannot be resolved:
i18next.init({
debug: true,
// ...
});This is the simplest first-line detection mechanism. Review the console during local development and integration testing to surface keys you have missed.
Fall back to another language
Use fallback languages to display the primary language when a translation is missing in the user's locale:
i18next.init({
fallbackLng: 'en',
// ...
});Instead of seeing welcome.title, the user sees "Welcome": recognizable English text rather than a raw key.
By default, i18next treats an empty string as a valid translation (returnEmptyString: true), and i18next-cli extract writes empty-string placeholders for new keys in secondary languages (the primary language gets the code default or the key itself). Without the next setting, those keys render as blank text instead of falling back. Set returnEmptyString: false so empty values count as missing:
i18next.init({
fallbackLng: 'en',
returnEmptyString: false,
// ...
});Provide inline default values
Pass a default value directly in the t() call:
t('welcome.title', { defaultValue: 'Welcome' })The default value is shown only when the key is missing in the active language and in every fallback language, because i18next checks fallbackLng first. This is more granular than fallbackLng, useful when a specific call needs its own last-resort text.
Capture missing keys at runtime with saveMissing
Set saveMissing: true and provide a missingKeyHandler to capture missing keys as they happen:
i18next.init({
saveMissing: true,
missingKeyHandler: (lngs, ns, key, fallbackValue) => {
// lngs is an array; forward to your logger, error tracker, etc.
},
// ...
});A custom missingKeyHandler replaces the backend call. When you use a backend that supports saving missing keys, such as i18next-locize-backend, leave the handler out: with saveMissing: true, i18next sends missing keys to the backend, and they appear in your Locize project. Translators fill them in (or Automatic Translation pre-fills them with AI) and the new translations are served via CDN with no redeploy. Keep saveMissing to development: it needs a write API key, and the i18next docs recommend disabling it in production. See Automating i18next Translations with saveMissing and Locize AI for the full setup. AI coding agents can check the same gaps through the Locize MCP server, whose find_missing_translations tool compares a target language against the reference language. This is how Locize closes the loop between code and translation:
Customize the missing-key behavior
i18next provides additional configuration options for missing-key handling: parseMissingKeyHandler for transforming the rendered output, appendNamespaceToMissingKey for diagnostics, and the missingKey event (i18next.on('missingKey', ...), fired only when saveMissing is on) for richer instrumentation.
Best practices for the i18next localization workflow
A handful of practices keep missing translations from compounding over time:
1. Establish a clear translation process. Define when keys are added, who translates them, and how updates are reviewed. See our guide on keeping track of new translations.
2. Maintain a glossary and style guide. Translators need consistent terminology, especially for product names and technical vocabulary. Locize integrates a glossary directly into the translation workflow.
3. Use consistent formatting and placeholders. Follow consistent formatting conventions and use placeholders effectively so translators know what is interpolated.
4. Version your translations. Use versioning and history so you can revert if a translation regresses and track changes over time.
Improve user experience when translations are missing
How you handle the missing case affects how users perceive the app:
Communicate clearly. If a translation is not available, an informative placeholder is better than a raw key. Use parseMissingKeyHandler or default values to render something readable.
Provide context and use variables properly. Translators do better work with context, and consistent variable usage prevents bugs where a placeholder is translated as literal text.
Watch text length. Translated text is often longer than the source; German, for example, frequently runs longer than English. Test your layout with realistic translations to avoid truncation or overflow.
Optimize i18next performance
As your translation footprint grows, performance considerations come into play:
1. Cache translations. Caching translations locally or via CDN reduces network requests on subsequent loads.
2. Bundle or split language files. Minify and bundle for smaller payloads, or use lazy loading to defer translations until they are needed.
3. Lazy-load namespaces. Load translations dynamically so the initial bundle stays small.
Frequently Asked Questions
It means i18next could not find a translation for that key, usually because the key is not in any of the loaded translation files, the namespace failed to load, or the file path is wrong. By default i18next returns the key itself as a fallback. Fix the underlying cause (extract the key, fix the loadPath, add the namespace) or configure a fallbackLng so users see a translated default instead of a raw key.
At build time, run i18next-cli status to get a completeness report across locales and namespaces, or status --hide-translated to see only the gaps. At runtime, enable debug: true to log a missingKey message to the console when a key cannot be resolved, or set saveMissing: true during development to capture missing keys via a missingKeyHandler (or, without a handler, send them to a backend like i18next-locize-backend so they land in Locize for translators to fill in).
Wire i18next-cli extract --ci or i18next-cli status into your CI pipeline. extract --ci exits non-zero if extraction updates any translation file, for example because a new key in code is not yet in your translation files (add --dry-run so nothing is written). status exits non-zero if a secondary locale has missing or empty values, or if a key used in code is absent from the primary language. Either gate blocks merges that would ship missing translations to production.
saveMissing: true (default false) tells i18next to report every key it cannot resolve: to your missingKeyHandler if you set one, otherwise to the create function of a backend that supports it, such as i18next-locize-backend, i18next-http-backend or i18next-fs-backend. A handler can log the key, write it to a file, or POST it anywhere. With i18next-locize-backend, missing keys are added to your Locize project so translators can fill them in, without manual key entry. Use it during development; the i18next docs recommend disabling it in production.
fallbackLng tells i18next which language to fall back to when a key is missing in the user's current language, e.g. show English text when the German translation is not ready yet. A default value is passed inline in the t() call and is shown only when the key is missing in the active language and in every fallback language. Default values are more granular; fallback languages are the project-wide safety net and are checked first.
Yes, when you generate types with i18next-cli types. The command reads your translation files and produces TypeScript definitions, so referencing a key that does not exist becomes a compile error. Combined with a strict tsconfig, CI catches misspelled keys before they ship. The types come from your primary-language files, so they do not catch untranslated secondary languages; use i18next-cli status for those.
During development, i18next captures missing keys via saveMissing and i18next-locize-backend sends them to Locize. Locize adds them to the project, optionally translates them with Automatic Translation, and translators fill in the rest. Once translations are published, they are served via the Locize CDN to your app with no redeploy needed. AI coding agents can check the same gaps with the find_missing_translations tool of the Locize MCP server.
Yes, treat them like any other source artifact. Commit the JSON files produced by extract so your repo is the source of truth and CI can verify completeness with status or extract --ci. If you use Locize, you can also configure locize-download to pull production translations as part of your build, but committing the extracted keys keeps the team in sync about what needs translating.
Conclusion
Missing translations are an inevitable part of multilingual development: keys get added, languages lag behind, files fail to load. What makes the difference is having both layers in place: build-time prevention with i18next-cli so missing keys never reach production, and runtime safeguards (fallbackLng, default values) so anything that slips through still renders something reasonable. Combine that with a translation management system like Locize, which captures saveMissing payloads, lets translators fill them in, and serves the result via CDN without a redeploy, and you have a workflow where missing translations get closed automatically.
For codebases that do not yet have i18next instrumentation in place, see From Hardcoded Strings to Global-Ready: The Modern React i18n Journey: the upstream version of "missing translations" is "missing t() calls entirely". i18next-cli lint reports hardcoded strings as errors (exiting non-zero, so it can gate CI too), and i18next-cli instrument can help wrap them.
Tired of managing translations by hand?
Locize is the translation management backend by the i18next team: CDN delivery, AI translation, in-context editing, no redeploys.
Start your free 14-day trial


