Quickstart

Set up PolyCLI and translate your first file in under 5 minutes.

You need a PolyCLI account and API key before running the CLI. Create a free account →

Initialise your project

No installation required — PolyCLI runs via npx. Run this in the root of the project you want to translate:

bash

npx @polycli/cli init

Answer the prompts. PolyCLI writes a buildtranslator.json file:

buildtranslator.json

{
  "sourceLanguage": "en",
  "targetLanguages": ["it", "es", "fr"],
  "localesPath": "./locales"
}

Create your source file

Add a JSON file for your source language:

locales/en.json

{
  "welcome": "Welcome, {{name}}!",
  "dashboard": {
    "title": "Your Dashboard",
    "credits": "You have {count, plural, one {# credit} other {# credits}} remaining."
  }
}

Get your API key

Go to your PolyCLI dashboard, copy your API key (starts with bt_live_). You can pass it inline or store it in an environment variable:

bash

# Option A — inline flag
npx @polycli/cli run --key bt_live_xxxxxxxxxxxxxxxxxxxx

# Option B — environment variable (recommended for CI/CD)
export POLYCLI_API_KEY=bt_live_xxxxxxxxxxxxxxxxxxxx

Run the translation

bash

npx @polycli/cli run

PolyCLI will:

Read locales/en.json
Detect that no lockfile exists yet — all keys are new
Send the strings to the translation API
Write locales/it.json, locales/es.json, locales/fr.json
Save a .translator-lock.json lockfile

locales/it.json

{
  "welcome": "Benvenuto, {{name}}!",
  "dashboard": {
    "title": "La tua Dashboard",
    "credits": "Hai {count, plural, one {# credito} other {# crediti}} rimanenti."
  }
}

Commit .translator-lock.json to version control. It is what allows PolyCLI to calculate the delta on subsequent runs.