Skip to main content
When i18n Doctor scans your repository, it generates a comprehensive health report that shows exactly where your translations need attention. This guide explains what each metric means and how to prioritize fixes.

​
Report Structure

Every scan report contains:
  • Summary metrics - Overall project health at a glance
  • Per-locale health cards - Detailed breakdown for each language
  • Issue lists - Specific keys that need attention
  • Coverage rankings - Locales sorted by completeness
Reports are sorted with the worst-performing locales first, making it easy to identify which languages need the most attention.

​
Coverage Percentage Explained

​
What is Coverage?

Coverage represents the percentage of your source locale’s keys that are properly translated in a target locale. 
coverage = (translatedKeys / totalSourceKeys) × 100
Where:
  • translatedKeys = keys that exist AND have non-empty values
  • totalSourceKeys = total keys in your source locale (e.g., en)

​
Coverage Ranges

Your locale is nearly complete. Focus on the few remaining keys and consider this locale production-ready.Action: Review untranslated keys for quality, then deploy with confidence.
Most content is translated, but there are noticeable gaps. Users will see English fallbacks in some areas.Action: Prioritize high-traffic UI strings and user-facing messages.
Significant portions are untranslated. User experience will be inconsistent.Action: Use Lingo.dev integration to bulk-translate missing keys, then review for accuracy.
This locale is incomplete and should not be deployed. Most content will appear in the source language.Action: Consider removing this locale from production or using one-click fix to bring it up to 100%.

​
Understanding Metrics

​
1. Missing Keys

Definition: Keys that exist in your source locale but are completely absent from the target locale file. Example: 
{
  "welcome": "Welcome",
  "login": "Log in",
  "signup": "Sign up"
}
Impact: Your app will fall back to the source language or show an error for these keys. Priority: 🔴 High - These are complete gaps in your localization.

​
2. Untranslated Keys

Definition: Keys that exist in the target locale but have empty string values. Example:
fr.json
{
  "welcome": "Bienvenue",
  "login": "",  // Key exists but empty
  "signup": "S'inscrire"
}
Impact: Empty strings may render as blank text in your UI, creating a poor user experience. Priority: 🔴 High - Worse than missing keys because they won’t trigger fallbacks.
Untranslated keys (empty strings) are often worse than missing keys. Many i18n libraries will display empty strings instead of falling back to the source language, leaving users with blank UI elements.

​
3. Orphan Keys

Definition: Keys that exist in the target locale but are NOT in the source locale. Example:
fr.json
{
  "welcome": "Bienvenue",
  "old_feature_label": "Ancienne fonctionnalité",  // Orphan
  "deprecated_button": "Bouton obsolète"  // Orphan
}
Common causes:
  • Refactored code where keys were renamed or removed
  • Copy-paste errors between locale files
  • Legacy features that were removed
Impact: Orphan keys don’t break functionality but bloat your locale files and make maintenance harder. Priority: 🟡 Low - Safe to remove, but not urgent.
Orphan keys are a good indicator of “translation debt.” Cleaning them up regularly keeps your locale files maintainable.

​
How to Prioritize Fixes

1

Start with the worst coverage

Reports sort locales by coverage (worst first). Focus on languages below 70% coverage.
2

Fix untranslated keys first

Empty string values are the most damaging because they create blank UI elements.
# Priority order:
# 1. Untranslated keys (empty strings)
# 2. Missing keys (absent from file)
# 3. Orphan keys (cleanup)
3

Use Lingo.dev for bulk translation

For locales with many missing/untranslated keys, use the “Fix with Lingo.dev” button to automatically translate everything, then review.
4

Clean up orphans

Once all locales are above 90% coverage, remove orphan keys to keep files clean.

​
Common Patterns

​
Nested Key Flattening

i18n Doctor flattens nested JSON structures with dot notation: 
{
  "auth": {
    "login": {
      "title": "Log In",
      "button": "Submit"
    }
  }
}
This makes it easy to identify exactly which keys are missing, even in deeply nested structures.

​
New Features = Coverage Drop

If you recently added new UI strings to your source locale, all other locales will show:
  • Decreased coverage percentage
  • New missing keys in the report
This is expected! Update your translations whenever you ship new features.

​
Partial Migrations

If you see many missing keys across ALL locales, it might indicate:
  • A recent key rename or restructuring
  • Incomplete migration from an old i18n library
  • Multiple source files that aren’t being detected
If your report shows unexpected results, verify that i18n Doctor is detecting all your locale files. Check the scan results for the list of detected files.

​
Reading the Summary

The summary section aggregates data across all locales:
MetricMeaning
Total LocalesNumber of target languages detected (excludes source locale)
Avg CoverageMean coverage across all locales - your overall i18n health score
Total MissingSum of all missing keys across all locales
Total UntranslatedSum of all empty string values across all locales
Total OrphanSum of all unused keys across all locales
Average Coverage is your most important metric. Aim for 85%+ to ensure a good multilingual user experience.

​
Next Steps

Supported Formats

Learn about JSON, YAML, and gettext file support

Lingo.dev Integration

Use AI-powered translation to fix missing keys

Build docs developers (and LLMs) love

Get started for freeTalk to us