CI: catch i18n problems on every pull request

Sonenta assesses the i18n impact of a pull request, self-namespaced keys, hardcoded strings, missing placeholders and translation-quality candidates, and reports them straight onto the diff. It is advisory by default, with the option to block a pull request on real structural errors.

What it checks

On the files a pull request touches:

Structural, self-namespaced keys. A key prefixed with its own namespace nests a redundant layer into the bundle and can make the SDK fall back silently to the source locale. This is the only check that can block a pull request.

Hardcoded strings. User-visible text not yet behind a key. Advisory.

Drifting placeholders. Interpolation variables ({{name}}, {count}, %{n}) that have drifted from the source. Advisory.

Translation-quality candidates. same_as_source, looks_like_raw_key and wrong_language. These are heuristics, so expect false positives on brands and acronyms. Always advisory.

Available today: the sonenta ci command

sonenta ci ships in @sonenta/cli and runs offline. Point it at a base ref and it prints a PR-ready report.

sonenta ci --base origin/main --source-lang en

Options: --base <ref> (default: the PR base, else origin/main), --source-lang <code> (enables the same-as-source check), --strict (non-zero exit when the status is FAIL), --format markdown|json, --out <file>, --dir <path>, --src <dir>. The command is aliased as check.

Wire it into a GitHub Action:

name: i18n
on: pull_request
jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @sonenta/cli ci --base "origin/${{ github.base_ref }}" --source-lang en

Offline, therefore blind to the glossary

sonenta ci has no access to your Sonenta glossary. The quality checks (same_as_source, looks_like_raw_key) can therefore wrongly flag terms deliberately kept in the source language, brands and proper nouns. They are advisory and never fail the build.

The authority on translation quality is validate_translations, which is online and glossary-aware. Run it before publishing.

The hosted GitHub App

Not publicly available yet

The hosted Sonenta i18n App is not on the GitHub Marketplace yet, and self-serve installation is not open. This section describes how it works; general availability will be confirmed here when it opens.

The hosted App posts a native GitHub Check Run on every pull request, with inline annotations at the exact file and line, and handles both advisory and blocking modes. It requests these repository permissions: Contents (read), Checks (read and write) and Pull requests (read and write), and subscribes to the Pull request event.

Configure with .sonenta/ci.json

Add a .sonenta/ci.json file at the root of your repository. It is read from the pull request HEAD:

{ "project_id": "<your Sonenta project UUID>" }

• project_id (required): the UUID of your Sonenta project. If it is missing or empty, the file is ignored.
• source_lang (optional): reserved for future use.

No other field is read.

Advisory or blocking

By default the check is advisory: results appear as annotations and the Check Run concludes neutral, so a pull request is never blocked.

To require a green structural check, turn on Block pull requests on i18n structure errors for the project, in the dashboard under GitHub CI. Only the structural check can block; quality, hardcoded-string and placeholder results stay advisory at all times.

Setting	Effect
Blocking off (default)	Structural results are warnings; the Check Run concludes neutral.
Blocking on	Structural results fail the check; the Check Run concludes failure.

What the result looks like

A Check Run named Sonenta i18n with a title, a summary and inline annotations, one per result at the file and line.

Annotation levels: structural = failure when blocking is on, otherwise warning; quality and hardcoded strings = warning. The run concludes failure (structural error with blocking on), neutral (advisory results only) or success (nothing found).

Next

• Versions and releases: what reaches the CDN, and when
• CLI reference: sonenta ci
• Key nesting: flat or nested keys, and the dotted-key trap