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 languageGitHub 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.
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 buildReport 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.
checkthen runs offline: it validates the manifest, notes that coverage needs a token, and exits with0. - 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
successwhen nothing is missing, outdated, or blocked, andneutralotherwise, 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,checkreportsGITHUB_CHECKS_PERMISSION_REQUIREDand annotates the job instead. - Failing the job. Add
--fail-on missing(orblocked, orstale) 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:
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:
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# Runs no repository code; uses a token stored as a CI secret.
linguana check --manifest .linguana/manifest.jsontest -n "$LINGUANA_PROJECT_TOKEN"
export LINGUANA_UPLOAD=true
export LINGUANA_TRANSLATE=true
bun run buildNext.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:
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:
npx @linguanahq/cli create app smoke-test \
--framework react --template blog --demo --yes --json
cd smoke-test
npm run buildCommands 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
| Value | Store | Browser-safe? |
|---|---|---|
LINGUANA_PROJECT_TOKEN | Protected CI environment secret | No |
LINGUANA_CHECK_TOKEN (separate coverage token, if used) | Repository secret, read only by the coverage job | No |
LINGUANA_AUTH_TOKEN (CLI account session, if used) | Protected secret, never in pull-request jobs | No |
| Provider API key | Translation service secret store | No |
VITE_LINGUANA_API_URL | Build/public variable | Yes |
| Publishable catalog key | Public runtime configuration | Yes |
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.
Keep pull requests fast, update development languages, and keep production releases deliberate.
Last updated November 17, 2026
Did this page get you to a working result?