Untranslated Values

Understanding untranslated value detection

Severity: Warning — does not affect exit code or fail CI builds.

Glot detects translation values in non-primary locales that are identical to the primary locale or are empty strings, which may indicate they haven’t been translated yet.

What Are Untranslated Values?

An untranslated value occurs when:

1. A key exists in both the primary locale and a non-primary locale
2. The value in the non-primary locale is identical to the primary locale, or is an empty string

This typically happens when:

• Locale files are copy-pasted and translations are forgotten
• A new key is added to all locales but only translated in the primary locale
• Translations are incomplete or rushed
• Translation tools or scripts create placeholder keys with empty values

Example

Primary locale file:

messages/en.json

{
  "common": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}

Non-primary locale with untranslated values (identical to primary):

messages/zh.json

{
  "common": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}

Glot output:

warning: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") identical in: zh
  = used: (no usages found)

warning: "common.cancel"  [untranslated]
  --> ./messages/en.json:4:1
  = note: ("Cancel") identical in: zh
  = used: (no usages found)

✘ 2 problems (0 errors, 2 warnings)

Empty String Values

Non-primary locale with empty string values:

messages/zh.json

{
  "common": {
    "submit": "",
    "cancel": "取消"
  }
}

Glot output:

warning: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") empty in: zh
  = used: (no usages found)

✘ 1 problems (0 errors, 1 warning)

When a key has both identical and empty values across different locales, both are shown:

warning: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") identical in: ja; empty in: zh
  = used: (no usages found)

The output shows:

• File location: Points to the primary locale file (en.json) as the source of truth
• Note: Shows the value and which locales have identical or empty (untranslated) values
• Used: Shows where the key is used in code (clickable in IDEs), or “(no usages found)” if unused

Detection Rules

Glot applies these rules when detecting untranslated values:

Only Non-Primary Locales Are Checked

The primary locale (defined in .glotrc.json) is skipped since it’s the source of truth:

.glotrc.json

{
  "primaryLocale": "en"
}

With this config, messages/en.json is never checked for untranslated values.

Values Must Contain Alphabetic Characters

Pure numbers and symbols are skipped since they’re often legitimately the same across locales:

{
  "common": {
    "year": "2024",
    "separator": "---",
    "currency": "$"
  }
}

These won’t be flagged even if identical across locales.

Empty String Values Are Flagged

Empty string values in non-primary locales are always flagged, as they clearly indicate missing translations:

messages/zh.json

{
  "common": {
    "greeting": ""
  }
}

This will be flagged regardless of the primary locale value.

Exact Match Required

For identical value detection, only values that are exactly identical to the primary locale are flagged:

messages/en.json

{
  "common": {
    "greeting": "Hello"
  }
}

messages/de.json

{
  "common": {
    "greeting": "Hello"
  }
}

This would be flagged. But if the German value was “hello” (lowercase), it would not be flagged.

Severity

Untranslated values are reported as warnings (not errors) because:

• Some values legitimately remain the same across languages (brand names, technical terms, etc.)
• They don’t break functionality
• They’re informational and may not require action

Running Untranslated Detection

npmbash npx glot check untranslated

pnpmbash pnpm exec glot check untranslated

yarnbash yarn glot check untranslated

bunbash bunx glot check untranslated

Or run all checks including untranslated:

npmbash npx glot check

pnpmbash pnpm exec glot check

yarnbash yarn glot check

bunbash bunx glot check

Fixing Untranslated Values

1. Run Check

   npm

   npx glot check untranslated
   

   pnpm

   pnpm exec glot check untranslated
   

   yarn

   yarn glot check untranslated
   

   bun

   bunx glot check untranslated
   
2. Review Issues

   For each flagged key, determine if it needs translation or should remain the same.

3. Translate Values

   Update the non-primary locale files with proper translations:

   messages/zh.json

   {
     "common": {
       "submit": "提交",
       "cancel": "取消"
     }
   }
   
4. Verify

   Run the check again to confirm translations are applied:

   npm

   npx glot check untranslated
   

   pnpm

   pnpm exec glot check untranslated
   

   yarn

   yarn glot check untranslated
   

   bun

   bunx glot check untranslated
   

Common Scenarios

Legitimate Same Values

Some values should remain identical across locales:

{
  "brand": {
    "name": "Acme Corp",
    "tagline": "JavaScript"
  }
}

In these cases, you can safely ignore the warning.

Partial Translations

When adding new features, it’s common to copy keys from the primary locale and forget to translate some:

messages/ja.json

{
  "newFeature": {
    "title": "New Feature",
    "description": "Check out our new feature"
  }
}

These should be translated to Japanese.

Placeholder Text

Sometimes developers use English placeholder text intending to translate later:

messages/fr.json

{
  "dashboard": {
    "welcome": "Welcome back!"
  }
}

The untranslated check helps catch these before they reach production.

Empty Strings from Translation Tools

Some translation tools or scripts create keys with empty string values as placeholders:

messages/ko.json

{
  "newFeature": {
    "title": "",
    "description": ""
  }
}

These are detected and reported as untranslated.

Related

Check Command

Run untranslated value detection

Missing Keys

Find keys used but not defined

Orphan Keys

Find unused translation keys

Configuration

Configure primary locale