Untranslated Values

Understanding untranslated value detection

Severity: Error when used in source; Warning when no usage is found. Used untranslated values cause exit code 1 by default.

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 when these keys are used in source:

error: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") identical in: zh
  = used: ./src/app.tsx:10:18

error: "common.cancel"  [untranslated]
  --> ./messages/en.json:4:1
  = note: ("Cancel") identical in: zh
  = used: ./src/app.tsx:11:18

✘ 2 problems (2 errors, 0 warnings)

Empty String Values

Non-primary locale with empty string values:

messages/zh.json

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

Glot output when the key is used in source:

error: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") empty in: zh
  = used: ./src/app.tsx:10:18

✘ 1 problems (1 error, 0 warnings)

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

error: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") identical in: ja; empty in: zh
  = used: ./src/app.tsx:10:18

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 errors by default when the key is used in source because real untranslated UI text reaches users as a product issue.

If glot cannot find any source usage for the key, the issue is reported as a warning by default. That means the catalog value still looks untranslated, but glot has not proven that it reaches users. You can still make catalog-only untranslated values fail CI with:

{
  "severities": {
    "untranslated": "error"
  }
}

If a value is intentionally identical across locales (brand names, technical terms, file names, etc.), use a targeted suppression comment near the usage:

// glot-disable-next-line untranslated
return <span>{t("brandName")}</span>;

For existing projects, glot baseline --rules untranslated --apply can insert suppression comments for current untranslated issues that have source usages. Catalog-only untranslated values with no source usage cannot be suppressed with source comments; translate them, remove unused keys, or use a project-wide severities.untranslated policy.

If your project wants a broader policy change, you can downgrade the rule in .glotrc.json:

{
  "severities": {
    "untranslated": "warning"
  }
}

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, add a targeted glot-disable-next-line untranslated comment near the usage, or use a project-wide severity override if your team intentionally treats these as warnings.

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