CI/CD

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

Authentication

Create an API key in the dashboard (Settings → API Keys) and expose it as a secret:

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.

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.

GitHub Actions

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

      - 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. 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 rather than babelize auth login (the stored session won't survive the runner).