> ## Documentation Index
> Fetch the complete documentation index at: https://glotctl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Untranslated Values

> Understanding untranslated value detection

<Info>**Severity: Warning** — does not affect exit code or fail CI builds.</Info>

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:

```json messages/en.json theme={null}
{
  "common": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}
```

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

```json messages/zh.json theme={null}
{
  "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:

```json messages/zh.json theme={null}
{
  "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:

```json .glotrc.json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json messages/zh.json theme={null}
{
  "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:

```json messages/en.json theme={null}
{
  "common": {
    "greeting": "Hello"
  }
}
```

```json messages/de.json theme={null}
{
  "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

<Tabs syncKey="pkg">
  <Tab title="npm">`bash npx glot check untranslated `</Tab>
  <Tab title="pnpm">`bash pnpm exec glot check untranslated `</Tab>
  <Tab title="yarn">`bash yarn glot check untranslated `</Tab>
  <Tab title="bun">`bash bunx glot check untranslated `</Tab>
</Tabs>

Or run all checks including untranslated:

<Tabs syncKey="pkg">
  <Tab title="npm">`bash npx glot check `</Tab>
  <Tab title="pnpm">`bash pnpm exec glot check `</Tab>
  <Tab title="yarn">`bash yarn glot check `</Tab>
  <Tab title="bun">`bash bunx glot check `</Tab>
</Tabs>

## Fixing Untranslated Values

<Steps>
  <Step title="Run Check">
    <Tabs syncKey="pkg">
      <Tab title="npm">
        ```bash theme={null}
        npx glot check untranslated
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm exec glot check untranslated
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn glot check untranslated
        ```
      </Tab>

      <Tab title="bun">
        ```bash theme={null}
        bunx glot check untranslated
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Review Issues">
    For each flagged key, determine if it needs translation or should remain the same.
  </Step>

  <Step title="Translate Values">
    Update the non-primary locale files with proper translations:

    ```json messages/zh.json theme={null}
    {
      "common": {
        "submit": "提交",
        "cancel": "取消"
      }
    }
    ```
  </Step>

  <Step title="Verify">
    Run the check again to confirm translations are applied:

    <Tabs syncKey="pkg">
      <Tab title="npm">
        ```bash theme={null}
        npx glot check untranslated
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm exec glot check untranslated
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn glot check untranslated
        ```
      </Tab>

      <Tab title="bun">
        ```bash theme={null}
        bunx glot check untranslated
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Common Scenarios

### Legitimate Same Values

Some values should remain identical across locales:

```json theme={null}
{
  "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:

```json messages/ja.json theme={null}
{
  "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:

```json messages/fr.json theme={null}
{
  "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:

```json messages/ko.json theme={null}
{
  "newFeature": {
    "title": "",
    "description": ""
  }
}
```

These are detected and reported as untranslated.

## Related

<CardGroup cols={2}>
  <Card title="Check Command" icon="terminal" href="/commands/check">
    Run untranslated value detection
  </Card>

  <Card title="Missing Keys" icon="triangle-exclamation" href="/detection/missing-keys">
    Find keys used but not defined
  </Card>

  <Card title="Orphan Keys" icon="broom" href="/detection/orphan-keys">
    Find unused translation keys
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Configure primary locale
  </Card>
</CardGroup>