@kopynator/cli

The official Command Line Interface for Kopynator. Manage your internationalization workflow directly from your terminal.

Languages / Idiomas: English · Español

English

Installation

You don't need to install it globally! We recommend using npx for the latest version:

npx -y @kopynator/cli <command>

If you prefer a global installation:

npm install -g @kopynator/cli

Commands

| Command | What it does | | --- | --- | | init | Sets up Kopynator in your project (framework detection, config injection). | | check | Validates local translation files: JSON syntax, broken references, duplicate global keys. | | sync | Downloads translations from Kopynator Cloud into local JSON files. | | upload | Uploads a local JSON file to Kopynator Cloud. | | limits | Shows your plan's limits and current usage. | | help | Prints help for all commands. |

1. init

Sets up Kopynator in your project. Auto-detects your framework (Angular, React, Vue, React Native, Ionic) and either injects provideKopynator(...) directly into your app config, or falls back to creating a kopynator.config.json file. Interactively asks for your default locale and supported languages.

npx -y @kopynator/cli init

2. check

Validates your local translation files. Three things, in order:

1. JSON syntax — every locale file must parse.
2. Broken references — translation keys used in your source code (| kopy, [kopy]="'...'", .translate()/.t()) that don't exist in any locale file.
3. Duplicate global keys — keys whose value duplicates an existing global.* key, so your team converges on one canonical key instead of silently drifting into copies.

Useful for CI/CD pipelines and pre-commit hooks — it exits with a non-zero code on failure.

npx -y @kopynator/cli check

Flags:

• --base-ref <ref> — git ref to diff against when deciding which duplicate keys are new (default: master). Duplicates that already existed at that ref aren't re-flagged, so adopting check doesn't force you to clean up all pre-existing debt at once.
• --update-baseline — accepts every currently-missing key as backlog, writing kopynator.i18n-baseline.json. From then on, check only fails on keys that go missing after that point.
• --all — lists every missing key (baseline + new), tagging which ones are already accepted.

Two optional project-root config files:

• kopynator.i18n-baseline.json — { "keys": [...] }, written automatically by --update-baseline.
• kopynator.i18n-safelist.json — { "dynamicPrefixes": ["status."] }. Protects key families built dynamically at runtime (e.g. `status.${s}`) from being flagged as missing. You can also declare a prefix inline, right next to the code that uses it, with a comment: // kopynator-keys: status.*.

Set KOPYNATOR_I18N_SKIP=1 to bypass the check entirely (e.g. an emergency commit).

# CI example: only fail on regressions since main
npx -y @kopynator/cli check --base-ref origin/main

# Adopt the check on a legacy project without a big-bang cleanup
npx -y @kopynator/cli check --update-baseline

3. sync

Downloads translations from the Kopynator Cloud and saves them as local JSON files (e.g. src/assets/i18n/en.json). On first run it asks how you want the output formatted (nested vs. flat keys, pretty-print, indentation) and remembers your choice in kopynator.sync.config.json.

npx -y @kopynator/cli sync

4. upload

Uploads a JSON translation file to the Kopynator Cloud. Keys are merged/updated for the given language. Uses the same API key (token) as your app or kopynator.config.json.

Project: the target project is determined by the token. Each token is linked to one project when created in Dashboard → Settings → Tokens. To upload to a different project, use that project's token.

# Language inferred from filename (es.json → es)
npx -y @kopynator/cli upload --file=src/assets/i18n/es.json

# Explicit language
npx -y @kopynator/cli upload --file=locales/en.json --lang=en

After uploading, run sync to download the latest state from the cloud if needed.

5. limits

Shows your current plan, and per-organization limits and usage (projects, translation keys, members). Reads the same API key resolution as sync/upload (kopynator.config.json, app.config.ts/app.module.ts, or KOPYNATOR_API_KEY).

npx -y @kopynator/cli limits

6. help

Prints help for every command.

npx -y @kopynator/cli help

Configuration

The init command creates a kopynator.config.json file in your root (used as a fallback when it can't inject config directly into your app):

{
  "apiKey": "YOUR_API_KEY",
  "defaultLocale": "en",
  "languages": ["en", "es"],
  "mode": "local"
}

For CI environments without a config file, set KOPYNATOR_API_KEY (and optionally KOPYNATOR_BASE_URL) instead.

Español

Instalación

No hace falta instalarlo globalmente. Recomendamos usar npx para tener siempre la última versión:

npx -y @kopynator/cli <comando>

Si prefieres instalarlo de forma global:

npm install -g @kopynator/cli

Comandos

| Comando | Qué hace | | --- | --- | | init | Configura Kopynator en tu proyecto (detecta el framework e inyecta la configuración). | | check | Valida los ficheros de traducción locales: sintaxis JSON, referencias rotas, claves globales duplicadas. | | sync | Descarga las traducciones de Kopynator Cloud a ficheros JSON locales. | | upload | Sube un fichero JSON local a Kopynator Cloud. | | limits | Muestra los límites de tu plan y el uso actual. | | help | Muestra la ayuda de todos los comandos. |

1. init

Configura Kopynator en tu proyecto. Detecta automáticamente el framework (Angular, React, Vue, React Native, Ionic) e inyecta provideKopynator(...) directamente en la configuración de tu app, o crea un kopynator.config.json si no puede hacerlo. Te pregunta interactivamente el idioma por defecto y los idiomas que quieres soportar.

npx -y @kopynator/cli init

2. check

Valida tus ficheros de traducción locales. Comprueba tres cosas, en este orden:

1. Sintaxis JSON — todos los ficheros de idioma deben parsear correctamente.
2. Referencias rotas — claves de traducción usadas en tu código (| kopy, [kopy]="'...'", .translate()/.t()) que no existen en ningún fichero de idioma.
3. Claves globales duplicadas — claves cuyo valor duplica el de una clave global.* ya existente, para que el equipo converja en una única clave canónica en vez de ir creando copias sin darse cuenta.

Útil en pipelines de CI/CD y hooks de pre-commit — termina con código de salida distinto de cero si falla.

npx -y @kopynator/cli check

Flags:

• --base-ref <ref> — referencia git contra la que comparar para decidir qué claves duplicadas son nuevas (por defecto: master). Los duplicados que ya existían en esa referencia no se vuelven a marcar, así que adoptar check no obliga a limpiar toda la deuda existente de golpe.
• --update-baseline — acepta todas las claves actualmente rotas como deuda pendiente, escribiendo kopynator.i18n-baseline.json. A partir de ahí, check solo falla con claves que se rompan después de ese punto.
• --all — lista todas las claves rotas (aceptadas + nuevas), indicando cuáles ya están aceptadas.

Dos ficheros de configuración opcionales en la raíz del proyecto:

• kopynator.i18n-baseline.json — { "keys": [...] }, se escribe automáticamente con --update-baseline.
• kopynator.i18n-safelist.json — { "dynamicPrefixes": ["status."] }. Protege familias de claves construidas dinámicamente en tiempo de ejecución (p. ej. `status.${s}`) para que no se marquen como rotas. También puedes declarar un prefijo en línea, junto al código que lo usa, con un comentario: // kopynator-keys: status.*.

Define KOPYNATOR_I18N_SKIP=1 para saltarte el check por completo (p. ej. un commit de emergencia).

# Ejemplo de CI: solo falla con regresiones desde main
npx -y @kopynator/cli check --base-ref origin/main

# Adoptar el check en un proyecto legacy sin limpieza masiva previa
npx -y @kopynator/cli check --update-baseline

3. sync

Descarga las traducciones de Kopynator Cloud y las guarda como ficheros JSON locales (p. ej. src/assets/i18n/en.json). La primera vez te pregunta cómo quieres el formato de salida (claves anidadas o planas, formato legible, indentación) y recuerda tu elección en kopynator.sync.config.json.

npx -y @kopynator/cli sync

4. upload

Sube un fichero JSON de traducción a Kopynator Cloud. Las claves se fusionan/actualizan para el idioma indicado. Usa la misma API key (token) que tu app o kopynator.config.json.

Proyecto: el proyecto de destino lo determina el token. Cada token está vinculado a un proyecto al crearse en Dashboard → Settings → Tokens. Para subir a otro proyecto, usa el token de ese proyecto.

# Idioma inferido del nombre del fichero (es.json → es)
npx -y @kopynator/cli upload --file=src/assets/i18n/es.json

# Idioma explícito
npx -y @kopynator/cli upload --file=locales/en.json --lang=en

Después de subir, ejecuta sync si necesitas descargar el estado más reciente de la nube.

5. limits

Muestra tu plan actual y los límites y uso por organización (proyectos, claves de traducción, miembros). Resuelve la API key igual que sync/upload (kopynator.config.json, app.config.ts/app.module.ts, o KOPYNATOR_API_KEY).

npx -y @kopynator/cli limits

6. help

Muestra la ayuda de todos los comandos.

npx -y @kopynator/cli help

Configuración

El comando init crea un fichero kopynator.config.json en la raíz (se usa como alternativa cuando no puede inyectar la configuración directamente en tu app):

{
  "apiKey": "YOUR_API_KEY",
  "defaultLocale": "en",
  "languages": ["en", "es"],
  "mode": "local"
}

Para entornos de CI sin fichero de configuración, define KOPYNATOR_API_KEY (y opcionalmente KOPYNATOR_BASE_URL).