---
title: "CI"
description: "Fail a build on broken keys, annotate pull requests, upload SARIF and publish a static report."
canonical_url: "https://x18n.dev/surfaces/ci"
---
# CI

> Fail a build on broken keys, annotate pull requests, upload SARIF and publish a static report.

`x18n check` exits with code 1 when it finds errors, so any CI fails on broken keys without more setup. The examples on this page use GitHub Actions. They assume that `x18n` is a dev dependency of the project. See [Getting started](https://x18n.dev/guide/getting-started#install).

## GitHub Actions

This workflow checks every push and pull request. The `github` reporter turns each diagnostic into an annotation on the changed line of the pull request. The `pretty` reporter prints the usual output to the log:

```yaml [.github/workflows/i18n.yml]
name: i18n

on:
  push:
    branches: [main]
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v5
        with:
          node-version: lts/*
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec x18n check --reporter github --reporter pretty
```

## Job summary

The `markdown` reporter writes a summary with a coverage table per locale and a table of diagnostics. Write it to the job summary of GitHub Actions:

```yaml
- run: pnpm exec x18n check --reporter markdown --output "$GITHUB_STEP_SUMMARY" --reporter github
```

The first `--output` belongs to the first `--reporter`. Here, the markdown goes to the summary file and the annotations go to stdout. The same markdown also suits a pull request comment.

## Code scanning

The `sarif` reporter writes SARIF 2.1.0. Upload it to show the diagnostics in the code scanning view of GitHub:

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      # checkout, setup and install as above
      - run: pnpm exec x18n check --reporter sarif --output x18n.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: x18n.sarif
```

`if: always()` uploads the file also when the check step fails.

## Choose what fails the build

By default, errors fail the build and warnings do not. Three options change that:

- `--strict` turns every warning into an error.
- `--max-warnings <n>` fails the build when there are more than `n` warnings. Use it to stop the number of warnings from growing.
- `checks` in the config changes the severity of a single check, for example `'unused-key': 'error'`.

On a project with many known problems, commit a [baseline](https://x18n.dev/surfaces/cli#baseline) with `x18n check --update-baseline`. The build then fails only on new diagnostics.

To check only some problems in a step, use `--only`. To check one locale, use `--locale`:

```sh
x18n check --only placeholder-mismatch,invalid-syntax --locale de
```

## Publish the report

`x18n build` writes a static, read-only copy of the [UI](https://x18n.dev/surfaces/ui). Upload it as an artifact, or deploy it to any static host:

```yaml
- run: pnpm exec x18n build --out-dir i18n-report
- uses: actions/upload-artifact@v4
  with:
    name: i18n-report
    path: i18n-report
```

## Other CI services

Every CI can run `x18n check`. Use the `pretty` reporter for the log, the `json` reporter for your own tools, and the `sarif` reporter for services that read SARIF. In a monorepo, `x18n check` checks every project. Add `--project <name>` to check one.


## Sitemap

See the full [sitemap](https://x18n.dev/sitemap.md) for all pages.
