CI/CD

Babelize is designed to run headlessly in CI. Use an API key for authentication, --json for machine-readable output, and --no-poll/--no-pr to control how a run completes.

Authentication

Create an API key at app.babelize.co/api-keys and expose it as a secret. Platform commands (projects, run, pr, …) read it as BABELIZE_TOKEN:

export BABELIZE_TOKEN=bblz_sk_xxxxxxxx

The CLI also accepts --token <token>. Prefer the environment variable so the token never appears in shell history or process listings.

Non-interactive mode

The CLI never blocks on prompts when running headlessly. Set CI=true (most CI systems do this automatically) or pass --yes/--non-interactive:

CI=true babelize run start -p <project-id> -l es,fr

In non-interactive mode, missing required flags exit with USAGE (2) and an actionable message instead of prompting. Bare babelize with no terminal prints the help instead of starting the guided flow.

Never rely on a prompt being "cancelled" — a cancelled prompt exits with CANCEL (128), which fails the pipeline step. Always pass the flags you need.

Translate in the pipeline (no cloud project)

babelize start runs the same local translation as npx babelize, without questions when you pass the languages. Set the API key as BABELIZE_API_KEY (or an LLM key of your own, such as ANTHROPIC_API_KEY):

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
- name: Translate
  env:
    BABELIZE_API_KEY: ${{ secrets.BABELIZE_API_KEY }}
  run: npx babelize start --to fr,de --yes
- name: Check locale files
  run: npx babelize check

The translated files are left in the runner's working tree: commit them in a later step, or open a pull request with an action of your choice. It needs a clean checkout; it never runs git init without a person there to confirm. See Translate Locally for babelize translate, its --json report and exit codes, and Check Translations for babelize check.

GitHub Actions (cloud project)

name: Translate
on:
  push:
    branches: [main]
    paths:
      - 'src/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Babelize CLI
        run: npm install -g @babelize/cli

      - name: Run translation
        env:
          BABELIZE_TOKEN: ${{ secrets.BABELIZE_TOKEN }}
        run: |
          PROJECT_ID=$(babelize projects list --json | jq -r '.[] | select(.name=="My App") | .id')
          BABEL_ID=$(babelize run start -p "$PROJECT_ID" -l es,fr --no-poll --json | jq -r '.babel_id')
          babelize run status "$BABEL_ID" --watch --json

The run status --watch --json step blocks until the run completes and emits the final status as JSON, so a failing translation run fails the pipeline.

Generate the PR

Set --no-pr to control PR creation separately, then create it explicitly:

- name: Raise PR
  env:
    BABELIZE_TOKEN: ${{ secrets.BABELIZE_TOKEN }}
  run: babelize pr raise "$PROJECT_ID"

Exit Codes

Deterministic output

Babelize translation runs are incremental: only changed strings are re-translated, and cached translations are reused. Local runs (babelize start, babelize translate) keep this in .babelize/local/babelize-lock.json; commit it so CI reuses it. The SDK build plugins write a deterministic babelize-lock.json that pins translations for reproducible builds. See the SDK docs for lockfile details.

Gotchas

• Always pass --no-poll when you don't want to block, and poll separately with run status --watch --json.
• Pass --no-pr if you don't want an automatic PR from a CI run (or you'll handle PRs yourself).
• On ephemeral runners, use BABELIZE_TOKEN / BABELIZE_API_KEY rather than babelize auth login (the stored session won't survive the runner).
• The CLI needs Node.js 22 or later.