docs

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.

terminal
npx @linguanahq/cli check
npx @linguanahq/cli check --locale fr de --fail-on missing
OptionDescription
--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
--path-prefix <dir>Repository path of the app, added to manifest file paths for annotations. Default: inferred from the manifest location and Git
--jsonPrint 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:

StateMeaning
ReadyThe latest version is accepted and was translated from the current source text
Needs reviewThe latest version matches the current source text and is waiting for review
OutdatedA translation exists, but for an earlier version of the source text
MissingThere is no translation, or the latest version was rejected
BlockedThe 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.

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

CodeWhen
0Coverage was reported, or the check ran offline
1The --fail-on level was reached, or the request failed
2The 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

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

Did this page get you to a working result?

On this page

No Headings