---
title: "Check translation coverage"
description: "Run linguana check in pull requests to report missing and outdated translations without starting paid work."
canonical_url: "https://docs.linguana.dev/docs/cli/check"
markdown_url: "https://docs.linguana.dev/docs/cli/check.md"
x_farming_labs_generated_preamble: true
---

# Check translation coverage
URL: /docs/cli/check
LLM index: /llms.txt
Description: Run linguana check in pull requests to report missing and outdated translations without starting paid work.
Related: /docs/automate/ci-cd, /docs/cli/commands

# Check translation coverage with `check`

`check` reads the manifest an extraction-only build writes to `.linguana/manifest.json` and asks Linguana which strings already have a current translation in each target language. It never uploads the manifest, starts a translation run, or charges your organization.

```bash title="terminal"
npx @linguanahq/cli check
npx @linguanahq/cli check --locale fr de --fail-on missing
```

| Option | Description |
| --- | --- |
| `--manifest <path>` | Manifest to check. Default: `.linguana/manifest.json` |
| `--locale <codes...>` | Target languages to report. Default: every enabled target language |
| `--fail-on <level>` | `none` (default), `blocked`, `missing`, or `stale`. See [Exit codes](#exit-codes) |
| `--path-prefix <dir>` | Repository path of the app, added to manifest file paths for annotations. Default: inferred from the manifest location and Git |
| `--json` | Print the coverage result as JSON |

## What each state means

Each string is classified by its latest translation version in each language, the same way the Strings page counts them:

| State | Meaning |
| --- | --- |
| Ready | The latest version is accepted and was translated from the current source text |
| Needs review | The latest version matches the current source text and is waiting for review |
| Outdated | A translation exists, but for an earlier version of the source text |
| Missing | There is no translation, or the latest version was rejected |
| Blocked | The latest version fails a check under the current glossary and QA rules, such as a broken placeholder or a missing required term |

Strings that are not ready are not current in your catalogs until a development build translates them and a reviewer resolves them. Publishing remains a separate dashboard action.

## Authentication

`check` uses `LINGUANA_PROJECT_TOKEN` from the environment, then from `.env.local`. The token's project and environment decide which languages are reported, and the manifest's project ID must match the token.

Without a token, `check` runs offline: it validates the manifest, prints the number of strings, explains that coverage needs a token, and exits with `0`. Pull requests from forks never receive repository secrets, so they always run offline.

The API origin comes from `--api-url`, then `LINGUANA_API_URL`, then `linguana.json`.

## In GitHub Actions

When `GITHUB_ACTIONS` is `true`, `check` also:

- Sends the pull request's head commit, or `GITHUB_SHA` for other events, so Linguana can post a **Linguana translations** check run on that commit when the project has a connected GitHub repository.
- Appends a coverage table to the job summary.
- Prints up to 50 warning annotations for missing and outdated strings, unless Linguana already posted the check run with its own annotations.

The check run concludes `success` when nothing is missing, outdated, or blocked, and `neutral` otherwise, so it never blocks a merge by itself. Use `--fail-on` to fail the job instead. See [Automate translations in CI](/docs/automate/ci-cd).

Annotations need paths relative to the repository root. In a monorepo, `check` infers the app directory from the manifest location. If you check a downloaded manifest outside the app, pass `--path-prefix apps/web`.

## Exit codes

| Code | When |
| --- | --- |
| `0` | Coverage was reported, or the check ran offline |
| `1` | The `--fail-on` level was reached, or the request failed |
| `2` | The manifest is missing or invalid, or an option is invalid |

`--fail-on` is a threshold: `blocked` fails only on blocked strings, `missing` also fails on missing strings, and `stale` also fails on outdated strings.

## JSON output

```json title="output"
{
  "projectId": "proj_123",
  "environment": "development",
  "messageCount": 42,
  "locales": [
    { "code": "fr", "total": 42, "ready": 38, "needsReview": 1, "stale": 2, "missing": 1, "blocked": 0 }
  ],
  "unresolved": [{ "id": "checkout.title", "locale": "fr", "state": "missing" }],
  "unresolvedTotal": 3,
  "githubCheck": { "status": "created", "url": "https://github.com/acme/app/runs/1" }
}
```

`unresolved` lists at most 200 strings; `unresolvedTotal` counts all of them. `githubCheck.status` is `created`, `skipped`, or `failed`, with a `reason` code when it was not created. Offline runs print `{ "offline": true, "reason": "PROJECT_TOKEN_REQUIRED", "messageCount": 42 }`.

<ExpectedResult>
The command prints one line per target language and exits with `0`, or with `1` only when you set `--fail-on`.
</ExpectedResult>

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
