Quickstart

Get Started

This guide walks you through scanning a GitHub repository and understanding your localization health report.

No account required — Just paste a repo URL and scan. GitHub OAuth is optional for saving scan history.

Visit i18n.doctor

Navigate to https://i18n.doctor in your browser.You’ll see the main landing page with a repo input field.

Enter a GitHub Repository

Paste a public GitHub repository URL in one of these formats:

https://github.com/owner/repo
owner/repo
https://github.com/owner/repo/tree/main

Try this example: vercel/next.js or any repo you maintain with translation files

The scanner accepts:

Full GitHub URLs
Short owner/repo format
URLs with specific branches (e.g., /tree/develop)

Then click Scan Repo.

Wait for the Scan

The scanner performs the following steps automatically:

Fetches repo metadata — Validates the repo exists and gets the default branch
Retrieves the file tree — Pulls the complete directory structure via GitHub API

Detects locale files — Searches for translation files in common patterns:

✓ locales/
✓ i18n/
✓ messages/
✓ public/locales/
✓ src/locales/
✓ app/i18n/

Parses all locale files — Extracts key-value pairs from JSON, YAML, or .po files
Generates the health report — Compares target locales against the source locale

Typical scan time: 5-15 seconds for repos with 10-50 locale files

If no locale files are found, you’ll see:

No locale files found. 
We look for JSON/YAML/PO files in directories like 
locales/, i18n/, messages/, lang/, etc.

Review the Health Report

Once the scan completes, you’ll see a comprehensive dashboard with:

Summary Cards

Four key metrics at the top:

Metric	Description
Total Keys	Number of translation keys in the source locale (e.g., `en`)
Avg Coverage	Average coverage percentage across all target locales
Missing Keys	Total number of keys that exist in source but not in target locales
Orphan Keys	Keys present in target locales but absent from source (unused)

Repository Info

Just below the header, you’ll see badges showing:

Base path — Where locale files were found (e.g., locales/)
Style — flat (e.g., locales/en.json) or nested (e.g., locales/en/common.json)
Source locale — The reference locale used for comparison (usually en)

Locale Cards

Each target locale gets a card displaying:

fr85% coverage

36/42 keys translated · 6 issues

Color coding:

🟢 Green (≥90%) — Excellent coverage
🟠 Orange (60-89%) — Needs attention
🔴 Red (<60%) — Critical issues

Expand Locale Details

Click Show details on any locale card to see exactly what’s wrong:

Missing Keys

Keys that exist in the source locale but are absent from this target:

Missing keys (4)
• dashboard.welcome.title
• dashboard.welcome.subtitle
• settings.privacy.label
• settings.privacy.description

Impact: Users will see English fallbacks or blank strings.

Untranslated Keys

Keys that exist but have empty values:

// fr.json
{
  "welcome.title": "",  // ❌ Untranslated
  "welcome.subtitle": "Commencez ci-dessous"  // ✅ Translated
}

Impact: Same as missing keys — no text displayed.

Orphan Keys

Keys present in target locale but not in source:

Orphan keys (2)
• old_feature.title
• deprecated.message

Impact: Bloat in translation files. These keys are unused and can be safely removed.

Focus on missing and untranslated keys first — orphans are lower priority cleanup tasks.

Fix Issues with Lingo.dev (Coming Soon)

The “Fix with Lingo.dev” button will translate all missing/untranslated keys:

Click the fix button on the report page
Lingo.dev translates all gaps using context-aware AI
Preview a live diff of changes
Download a ZIP file with updated locale files
Optionally open a GitHub PR with the fixes

This feature is currently in development. For now, use the scan report to manually identify and fix issues.

Understanding the Scan Results

Example: Real Scan Output

Let’s walk through a real example. Suppose you scan a repo with this structure:

locales/
  en.json       (source, 42 keys)
  fr.json       (36 keys, 4 empty values)
  es.json       (28 keys)
  de.json       (40 keys, 3 orphan keys)

The report will show:

French (fr) — 85% coverage

Translated: 36/42 keys
Missing: 6 keys
Untranslated: 4 keys (empty strings in fr.json)
Orphan: 0 keys

Diagnosis: Missing 6 keys and 4 have empty values. Need to add 10 translations total.

Spanish (es) — 67% coverage

Translated: 28/42 keys
Missing: 14 keys
Untranslated: 0 keys
Orphan: 0 keys

Diagnosis: Missing 14 translations. File is outdated.

German (de) — 95% coverage

Translated: 40/42 keys
Missing: 2 keys
Untranslated: 0 keys
Orphan: 3 keys

Diagnosis: Nearly perfect! Missing only 2 keys. Has 3 orphan keys from old features.

Summary: Average coverage is 82%. German is in great shape, Spanish needs the most work.

Supported File Formats

The scanner automatically parses these formats:

JSON (nested)
YAML
PO (gettext)

{
  "app": {
    "title": "My App",
    "nav": {
      "home": "Home",
      "about": "About"
    }
  }
}

Flattened to: app.title, app.nav.home, app.nav.about

app:
  title: My App
  nav:
    home: Home
    about: About

Handles nested keys with indentation

msgid "app.title"
msgstr "My App"

msgid "app.nav.home"
msgstr "Home"

Extracts msgid / msgstr pairs

Common Issues

Repository not found

Causes:

Repo is private (only public repos are supported)
Incorrect owner or repo name
Repo was deleted or renamed

Solution: Verify the repo exists and is public at github.com/owner/repo

No locale files found

Causes:

Locale files are in an uncommon directory (e.g., assets/langs/)
Files use unsupported formats (e.g., .xml, .properties)

Solution:

Move files to standard paths: locales/, i18n/, public/locales/
Convert to JSON, YAML, or .po format

GitHub API rate limit exceeded

Causes:

Too many scans from the same IP (60/hour without auth)

Solution:

Sign in with GitHub OAuth for 5,000 requests/hour
Wait for the rate limit to reset (shown in error message)

Source locale not detected correctly

The scanner guesses the source locale using this heuristic:

Prefer en if present
Prefer en-us if en is absent
Fall back to first locale alphabetically

If the wrong locale is chosen, rename your source file to en.json or use a nested structure like locales/en/.

Next Steps

Core Features

Learn about scanning, health reports, and one-click fixes

Understanding Reports

Learn how to interpret scan results and prioritize fixes

API Reference

Integrate scans into your CI/CD pipeline with the REST API

Supported Formats

See all supported translation file formats and examples

Tips for Better Results

Use consistent directory structures — Keep all locales in the same folder with the same file names (e.g., locales/en.json, locales/fr.json)

Flatten deeply nested JSON — Prefer user.profile.name over { user: { profile: { name: "..." } } } for easier key diffing

Remove orphan keys regularly — Run scans before releases and clean up unused translations to reduce file size

Automate with CI/CD — Add the scan API to GitHub Actions to block merges when coverage drops below 80%

Get Started

Core Features

Guides

Architecture

Get Started

Summary Cards

Repository Info

Locale Cards

Missing Keys

Untranslated Keys

Orphan Keys

Understanding the Scan Results

Example: Real Scan Output

Supported File Formats

Common Issues

Next Steps

Core Features

Understanding Reports

API Reference

Supported Formats

Tips for Better Results

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Architecture

​Get Started

​Summary Cards

​Repository Info

​Locale Cards

​Missing Keys

​Untranslated Keys

​Orphan Keys

​Understanding the Scan Results

​Example: Real Scan Output

​Supported File Formats

​Common Issues

​Next Steps

Core Features

Understanding Reports

API Reference

Supported Formats

​Tips for Better Results

Build docs developers (and LLMs) love

Get Started

Summary Cards

Repository Info

Locale Cards

Missing Keys

Untranslated Keys

Orphan Keys

Understanding the Scan Results

Example: Real Scan Output

Supported File Formats

Common Issues

Next Steps

Tips for Better Results