> ## 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.

# glot check

> Run i18n checks on your codebase

The `check` command is the core of glot. It scans your codebase for internationalization issues.

## Usage

<CodeGroup>
  ```bash npm theme={null}
  npx glot check [CHECK_TYPES...] [OPTIONS]
  ```

  ```bash pnpm theme={null}
  pnpm exec glot check [CHECK_TYPES...] [OPTIONS]
  ```

  ```bash yarn theme={null}
  yarn glot check [CHECK_TYPES...] [OPTIONS]
  ```

  ```bash bun theme={null}
  bunx glot check [CHECK_TYPES...] [OPTIONS]
  ```
</CodeGroup>

## Check Types

You can run specific checks or all checks at once:

| Type            | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `hardcoded`     | Find untranslated text in JSX/TSX files                                     |
| `missing`       | Identify translation keys used in code but missing from locale files        |
| `orphan`        | Find keys in non-primary locales not present in primary locale              |
| `untranslated`  | Find values identical to primary locale that may need translation           |
| `unused`        | Find keys in primary locale that are not used in code                       |
| `replica-lag`   | Find keys in primary locale missing from other locales                      |
| `type-mismatch` | Find type conflicts between primary and replica locales (string vs array)   |
| `unresolved`    | Find keys that cannot be statically resolved (variables, template literals) |

### Severity

Each check type has a fixed severity level. **Errors** cause a non-zero exit code (exit 1); **warnings** do not.

| Type            | Severity | Exit Code |
| --------------- | -------- | --------- |
| `hardcoded`     | Error    | 1         |
| `missing`       | Error    | 1         |
| `type-mismatch` | Error    | 1         |
| `orphan`        | Warning  | 0         |
| `untranslated`  | Warning  | 0         |
| `unused`        | Warning  | 0         |
| `replica-lag`   | Warning  | 0         |
| `unresolved`    | Warning  | 0         |

<Tip>
  In CI pipelines, only errors will fail the build. Warnings are informational and won't block your workflow.
</Tip>

<CodeGroup>
  ```bash npm theme={null}
  # Run all checks (default)
  npx glot check

  # Run specific checks
  npx glot check hardcoded
  npx glot check missing
  npx glot check orphan
  npx glot check untranslated
  npx glot check unused
  npx glot check replica-lag
  npx glot check type-mismatch
  npx glot check unresolved

  # Run multiple specific checks
  npx glot check hardcoded missing

  ```

  ```bash pnpm theme={null}
  # Run all checks (default)
  pnpm exec glot check

  # Run specific checks
  pnpm exec glot check hardcoded
  pnpm exec glot check missing
  pnpm exec glot check orphan
  pnpm exec glot check untranslated
  pnpm exec glot check unused
  pnpm exec glot check replica-lag
  pnpm exec glot check type-mismatch
  pnpm exec glot check unresolved

  # Run multiple specific checks
  pnpm exec glot check hardcoded missing
  ```

  ```bash yarn theme={null}
  # Run all checks (default)
  yarn glot check

  # Run specific checks
  yarn glot check hardcoded
  yarn glot check missing
  yarn glot check orphan
  yarn glot check untranslated
  yarn glot check unused
  yarn glot check replica-lag
  yarn glot check type-mismatch
  yarn glot check unresolved

  # Run multiple specific checks
  yarn glot check hardcoded missing
  ```

  ```bash bun theme={null}
  # Run all checks (default)
  bunx glot check

  # Run specific checks
  bunx glot check hardcoded
  bunx glot check missing
  bunx glot check orphan
  bunx glot check untranslated
  bunx glot check unused
  bunx glot check replica-lag
  bunx glot check type-mismatch
  bunx glot check unresolved

  # Run multiple specific checks
  bunx glot check hardcoded missing
  ```
</CodeGroup>

## Options

<ParamField path="--source-root" type="string">
  Override the source code root directory. Defaults to the value from configuration file.
</ParamField>

<ParamField path="--messages-root" type="string">
  Override the messages directory path. Defaults to the value from configuration file.
</ParamField>

<ParamField path="--primary-locale" type="string">
  Override the primary locale. Defaults to the value from configuration file.
</ParamField>

<ParamField path="-v, --verbose" type="boolean" default="false">
  Enable verbose output for debugging.
</ParamField>

## Examples

### Basic Check

Check the current directory for all i18n issues:

<CodeGroup>
  ```bash npm theme={null}
  npx glot check
  ```

  ```bash pnpm theme={null}
  pnpm exec glot check
  ```

  ```bash yarn theme={null}
  yarn glot check
  ```

  ```bash bun theme={null}
  bunx glot check
  ```
</CodeGroup>

### Override Source Root

Check a specific source directory:

<CodeGroup>
  ```bash npm theme={null}
  npx glot check --source-root ./src
  ```

  ```bash pnpm theme={null}
  pnpm exec glot check --source-root ./src
  ```

  ```bash yarn theme={null}
  yarn glot check --source-root ./src
  ```

  ```bash bun theme={null}
  bunx glot check --source-root ./src
  ```
</CodeGroup>

### Verbose Mode

Get detailed output including scanned files:

<CodeGroup>
  ```bash npm theme={null}
  npx glot check -v
  ```

  ```bash pnpm theme={null}
  pnpm exec glot check -v
  ```

  ```bash yarn theme={null}
  yarn glot check -v
  ```

  ```bash bun theme={null}
  bunx glot check -v
  ```
</CodeGroup>

### Check Specific Issue Types

Run only hardcoded text detection:

<CodeGroup>
  ```bash npm theme={null}
  npx glot check hardcoded
  ```

  ```bash pnpm theme={null}
  pnpm exec glot check hardcoded
  ```

  ```bash yarn theme={null}
  yarn glot check hardcoded
  ```

  ```bash bun theme={null}
  bunx glot check hardcoded
  ```
</CodeGroup>

Run hardcoded and missing key checks:

<CodeGroup>
  ```bash npm theme={null}
  npx glot check hardcoded missing
  ```

  ```bash pnpm theme={null}
  pnpm exec glot check hardcoded missing
  ```

  ```bash yarn theme={null}
  yarn glot check hardcoded missing
  ```

  ```bash bun theme={null}
  bunx glot check hardcoded missing
  ```
</CodeGroup>

## Output Format

Glot displays issues in a compiler-like format:

```
error: "Submit"  hardcoded-text
  --> ./src/components/Button.tsx:5:22
  |
5 |     return <button>Submit</button>;
  |                    ^

warning: common.oldKey  orphan-key
  --> ./messages/en.json
  |
  | Key exists in locale file but is not used in code
  |

✘ 2 problems (1 error, 1 warning)
```

### Issue Severity

| Severity | Exit Code | Description                                                                 |
| -------- | --------- | --------------------------------------------------------------------------- |
| Error    | 1         | Hardcoded text, missing keys, type mismatches                               |
| Warning  | 0         | Orphan keys, untranslated values, unused keys, replica-lag, unresolved keys |

## Understanding Issues

Each issue type is documented in detail on its own page. Here's a quick summary:

| Issue Type       | Severity | Description                                                 | Details                                       |
| ---------------- | -------- | ----------------------------------------------------------- | --------------------------------------------- |
| `hardcoded-text` | Error    | User-facing text not wrapped in `t()`                       | [Hardcoded Text](/detection/hardcoded-text)   |
| `missing-key`    | Error    | Key used in code but not defined in locale files            | [Missing Keys](/detection/missing-keys)       |
| `type-mismatch`  | Error    | Value type differs between locales (causes runtime crashes) | [Type Mismatch](/detection/type-mismatch)     |
| `orphan-key`     | Warning  | Key in non-primary locale but not in primary                | [Orphan Keys](/detection/orphan-keys)         |
| `untranslated`   | Warning  | Value identical to primary locale                           | [Untranslated](/detection/untranslated)       |
| `unused-key`     | Warning  | Key in primary locale but never used in code                | [Unused Keys](/detection/unused-keys)         |
| `replica-lag`    | Warning  | Key in primary locale missing from other locales            | [Replica Lag](/detection/replica-lag)         |
| `unresolved-key` | Warning  | Dynamic key that can't be statically analyzed               | [Unresolved Keys](/detection/unresolved-keys) |

### Quick Fix Guide

**Hardcoded text** → Replace with `t()` call, or suppress with `glot-disable-next-line`. See [Hardcoded Text](/detection/hardcoded-text).

**Missing keys** → Add the key to your locale file, or fix typos. See [Missing Keys](/detection/missing-keys).

**Type mismatches** → Ensure all locales use the same type (string/array/object). See [Type Mismatch](/detection/type-mismatch).

**Orphan keys** → Add to primary locale or remove with `glot clean --apply`. See [Orphan Keys](/detection/orphan-keys).

**Unused keys** → Remove with `glot clean --apply`. See [Unused Keys](/detection/unused-keys).

**Replica lag** → Add missing translations to non-primary locales. See [Replica Lag](/detection/replica-lag).

**Unresolved keys** → Add `glot-message-keys` annotations or run `glot fix --apply`. See [Unresolved Keys](/detection/unresolved-keys).

## Exit Codes

| Code | Meaning                              |
| ---- | ------------------------------------ |
| 0    | No errors found (warnings may exist) |
| 1    | Errors found                         |

This makes glot suitable for CI/CD pipelines where you want to fail builds on errors.

## Verbose Output

With `-v` flag, glot shows additional information:

```
Scanning directory: ./src
Found 42 TSX/JSX files
Checking file: ./src/components/Button.tsx
Checking file: ./src/components/Form.tsx
...

error: "Submit"  hardcoded-text
  --> ./src/components/Button.tsx:5:22
```

## CI Examples

Glot works well in CI pipelines. Here are GitHub Actions examples:

<CodeGroup>
  ```yaml npm .github/workflows/i18n.yml theme={null}
  name: i18n Check
  on: [push, pull_request]

  jobs:
    check:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-node@v4
        - run: npm ci
        - run: npx glot check
  ```

  ```yaml pnpm .github/workflows/i18n.yml theme={null}
  name: i18n Check
  on: [push, pull_request]

  jobs:
    check:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: pnpm/action-setup@v4
        - uses: actions/setup-node@v4
        - run: pnpm install
        - run: pnpm exec glot check
  ```

  ```yaml yarn .github/workflows/i18n.yml theme={null}
  name: i18n Check
  on: [push, pull_request]

  jobs:
    check:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-node@v4
        - run: yarn install
        - run: yarn glot check
  ```

  ```yaml bun .github/workflows/i18n.yml theme={null}
  name: i18n Check
  on: [push, pull_request]

  jobs:
    check:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: oven-sh/setup-bun@v2
        - run: bun install
        - run: bunx glot check
  ```
</CodeGroup>

## Related

<CardGroup cols={2}>
  <Card title="Hardcoded Text" icon="magnifying-glass" href="/detection/hardcoded-text">
    Detect untranslated text in JSX/TSX
  </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 in non-primary locales
  </Card>

  <Card title="Untranslated Values" icon="language" href="/detection/untranslated">
    Find values that may need translation
  </Card>

  <Card title="Unused Keys" icon="trash" href="/detection/unused-keys">
    Find keys in primary locale not used in code
  </Card>

  <Card title="Replica Lag" icon="clock" href="/detection/replica-lag">
    Find keys missing from replica locales
  </Card>

  <Card title="Type Mismatch" icon="exclamation-triangle" href="/detection/type-mismatch">
    Find type conflicts between locales
  </Card>

  <Card title="Unresolved Keys" icon="question" href="/detection/unresolved-keys">
    Find keys that cannot be statically resolved
  </Card>

  <Card title="Directives" icon="code" href="/directives">
    Suppress specific warnings
  </Card>
</CardGroup>