docs

Automate translations in CI

Keep pull requests fast, let development builds update translations, and keep production releases deliberate.

Pull request
  Check the app, find new text, and report missing translations

Development build
  Send new text for translation

Production release
  Review and publish the selected language

GitHub Actions example

The validation job needs no project token. The coverage job reads the manifest from the validation job and asks Linguana which strings are missing or outdated; it never uploads, translates, or charges. The development job runs only on main and receives its token from a protected CI environment.

.github/workflows/linguana.yml
name: Linguana

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      LINGUANA_UPLOAD: "false"
      LINGUANA_TRANSLATE: "false"
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.14
      - run: bun install --frozen-lockfile
      - run: bun run check-types
      - run: bun run docs:verify
      - name: Snapshot source
        run: bun run source:before
      - name: Extraction-only build
        run: bun run build
      - name: Verify source integrity
        run: bun run source:after
      - uses: actions/upload-artifact@v4
        with:
          name: linguana-manifest
          path: .linguana/manifest.json
          if-no-files-found: error
          retention-days: 14

  coverage:
    if: github.event_name == 'pull_request'
    needs: validate
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: linguana-manifest
          path: .linguana
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.14
      - name: Check translation coverage
        env:
          LINGUANA_API_URL: ${{ vars.LINGUANA_API_URL }}
          LINGUANA_PROJECT_TOKEN: ${{ secrets.LINGUANA_CHECK_TOKEN }}
        run: bunx @linguanahq/cli check --manifest .linguana/manifest.json

  translate-development:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: validate
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: linguana-development
    env:
      LINGUANA_API_URL: ${{ vars.LINGUANA_API_URL }}
      LINGUANA_PROJECT_TOKEN: ${{ secrets.LINGUANA_PROJECT_TOKEN }}
      LINGUANA_UPLOAD: "true"
      LINGUANA_TRANSLATE: "true"
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.14
      - run: bun install --frozen-lockfile
      - name: Upload and translate development catalog
        run: bun run build

Report translation coverage on pull requests

linguana check compares the manifest's strings with the translations Linguana already has and reports, per language, how many are ready, need review, are outdated, are missing, or are blocked by validation. It sends only string IDs, content hashes, and the first source location of each string. It never creates a build, starts a translation run, or charges your organization, so pull requests still never request paid work.

  • Token. Create a separate token for the development environment and store it as the repository secret LINGUANA_CHECK_TOKEN. Project tokens are not read-only yet: anyone holding it could upload builds for that environment. That is why the coverage job runs no repository code; it only downloads the manifest artifact and runs the published CLI.
  • Forks. Pull requests from forks do not receive secrets. check then runs offline: it validates the manifest, notes that coverage needs a token, and exits with 0.
  • Job summary and annotations. The coverage table is added to the job summary. Missing and outdated strings appear as warnings on the lines that use them.
  • Check run. When the project has a connected GitHub repository, Linguana also posts a Linguana translations check run on the pull request's head commit, with up to 50 annotations. It concludes success when nothing is missing, outdated, or blocked, and neutral otherwise, so it never blocks a merge. Posting it requires the Linguana GitHub App's Checks: Read and write permission; until an installation accepts that permission, check reports GITHUB_CHECKS_PERMISSION_REQUIRED and annotates the job instead.
  • Failing the job. Add --fail-on missing (or blocked, or stale) to make the job fail at that level. The default, none, only reports.

In a monorepo, check adds the app's directory to annotation paths when it can infer it. With a downloaded artifact, pass it explicitly, for example --path-prefix apps/web. See Check translation coverage.

Translate merged changes

Configure the plugin with an explicit charge and wait ceiling:

vite.config.ts
translation: process.env.LINGUANA_PROJECT_TOKEN &&
  process.env.LINGUANA_TRANSLATE !== "false"
  ? {
      enabled: true,
      maxChargeMicros: 100_000,
      waitTimeoutMs: 300_000,
      publish: "development",
    }
  : undefined,

Other CI providers

Use the same stage boundaries:

pull request validation
export LINGUANA_UPLOAD=false
export LINGUANA_TRANSLATE=false
bun install --frozen-lockfile
bun run check-types
bun run docs:verify
bun run source:before
bun run build
bun run source:after
pull request coverage, optional
# Runs no repository code; uses a token stored as a CI secret.
linguana check --manifest .linguana/manifest.json
authorized development build
test -n "$LINGUANA_PROJECT_TOKEN"
export LINGUANA_UPLOAD=true
export LINGUANA_TRANSLATE=true
bun run build

Next.js builds

The same stages apply to Next.js. next build writes .linguana/manifest.json, and uploads only when withLinguana receives upload: true and a token. Read the stage variables in next.config.ts:

next.config.ts
import { withLinguana } from "@linguanahq/next/plugin";

const token = process.env.LINGUANA_PROJECT_TOKEN;

export default withLinguana({
  projectId: process.env.LINGUANA_PROJECT_ID ?? "my-app",
  environment: "development",
  sourceLocale: "en",
  apiUrl: process.env.LINGUANA_API_URL,
  token,
  upload: process.env.LINGUANA_UPLOAD === "true",
  translation: token && process.env.LINGUANA_TRANSLATE !== "false"
    ? {
        enabled: true,
        maxChargeMicros: 100_000,
        waitTimeoutMs: 300_000,
        publish: "development",
      }
    : undefined,
})({});

With LINGUANA_UPLOAD: "false", the pull-request job still writes the manifest without remote requests. A Next.js build that enables upload without LINGUANA_PROJECT_TOKEN fails with Linguana upload requires a build token., so a misconfigured development job fails instead of silently skipping upload. See the Next.js guide.

The Linguana CLI in CI

Builds do not need the CLI. They authenticate with the project token above, which is scoped to one project and environment. check uses the same kind of project token to report coverage; see Report translation coverage on pull requests.

Use the CLI in pipelines for other checks that need no account, such as generating a template app in demo mode:

template smoke test
npx @linguanahq/cli create app smoke-test \
  --framework react --template blog --demo --yes --json
cd smoke-test
npm run build

Commands that create projects or credentials (link, env pull, and create app --connect) need a CLI account session. Run them on a workstation; in controlled automation only, supply the session as LINGUANA_AUTH_TOKEN from a protected secret. Never expose it to pull-request jobs. See Scripts and CI for noninteractive defaults, JSON output, and exit codes.

Keep credentials private

ValueStoreBrowser-safe?
LINGUANA_PROJECT_TOKENProtected CI environment secretNo
LINGUANA_CHECK_TOKEN (separate coverage token, if used)Repository secret, read only by the coverage jobNo
LINGUANA_AUTH_TOKEN (CLI account session, if used)Protected secret, never in pull-request jobsNo
Provider API keyTranslation service secret storeNo
VITE_LINGUANA_API_URLBuild/public variableYes
Publishable catalog keyPublic runtime configurationYes

Do not print environment values, authorization headers, source bodies, or translated bodies. Retain the manifest artifact, manifest hash, job IDs, request IDs, and redacted logs.

If something fails

Keep the error code, translation-run ID, and request ID from the build logs. Check an existing run before retrying so you do not start the same translation twice.

The build integration updates development languages only. Production remains an explicit dashboard action after review.

Next

Test the setup with Test your integration, then complete the production checklist.

Did this page get you to a working result?

On this page

No Headings