@kopynator/cli 1.5.0 → 1.6.0

package/README.md

@@ -3,7 +3,13 @@
 The official Command Line Interface for [Kopynator](https://kopynator.com).
 Manage your internationalization workflow directly from your terminal.
 
-## Installation
+**Languages / Idiomas:** [English](#english) · [Español](#español)
+
+---
+
+## English
+
+### Installation
 
 You don't need to install it globally! We recommend using `npx` for the latest version:
 
@@ -17,33 +23,67 @@ If you prefer a global installation:
 npm install -g @kopynator/cli
 ```
 
-## Commands
+### Commands
 
-### 1. Initialize
-Sets up Kopynator in your project. Creates the configuration file and guides you verify the setup.
+| Command | What it does |
+| --- | --- |
+| [`init`](#1-init) | Sets up Kopynator in your project (framework detection, config injection). |
+| [`check`](#2-check) | Validates local translation files: JSON syntax, broken references, duplicate global keys. |
+| [`sync`](#3-sync) | Downloads translations from Kopynator Cloud into local JSON files. |
+| [`upload`](#4-upload) | Uploads a local JSON file to Kopynator Cloud. |
+| [`limits`](#5-limits) | Shows your plan's limits and current usage. |
+| [`help`](#6-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.
 
 ```bash
 npx -y @kopynator/cli init
 ```
 
-### 2. Check / Validate
-Validates your local JSON translation files for syntax errors. Useful for CI/CD pipelines.
+#### 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.
 
 ```bash
 npx -y @kopynator/cli check
 ```
 
-### 3. Sync
-Downloads translations from the Kopynator Cloud and saves them as local JSON files (e.g. `src/assets/i18n/en.json`).
+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).
+
+```bash
+# 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`.
 
 ```bash
 npx -y @kopynator/cli sync
 ```
 
-### 4. Upload
-Uploads a JSON translation file to the Kopynator Cloud. Keys are merged/updated for the given language. Use the same API key (token) as in your app or `kopynator.config.json`.
+#### 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](https://www.kopynator.com/dashboard/settings/tokens). To upload to a different project, use that project’s token (e.g. another `apiKey` in `kopynator.config.json` or a separate config).
+**Project:** the target project is determined by the token. Each token is linked to one project when created in [Dashboard → Settings → Tokens](https://www.kopynator.com/dashboard/settings/tokens). To upload to a different project, use that project's token.
 
 ```bash
 # Language inferred from filename (es.json → es)
@@ -55,8 +95,140 @@ 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.
 
-## Configuration
-The `init` command creates a `kopynator.config.json` file in your root:
+#### 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`).
+
+```bash
+npx -y @kopynator/cli limits
+```
+
+#### 6. `help`
+Prints help for every command.
+
+```bash
+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):
+
+```json
+{
+  "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:
+
+```bash
+npx -y @kopynator/cli <comando>
+```
+
+Si prefieres instalarlo de forma global:
+
+```bash
+npm install -g @kopynator/cli
+```
+
+### Comandos
+
+| Comando | Qué hace |
+| --- | --- |
+| [`init`](#1-init-1) | Configura Kopynator en tu proyecto (detecta el framework e inyecta la configuración). |
+| [`check`](#2-check-1) | Valida los ficheros de traducción locales: sintaxis JSON, referencias rotas, claves globales duplicadas. |
+| [`sync`](#3-sync-1) | Descarga las traducciones de Kopynator Cloud a ficheros JSON locales. |
+| [`upload`](#4-upload-1) | Sube un fichero JSON local a Kopynator Cloud. |
+| [`limits`](#5-limits-1) | Muestra los límites de tu plan y el uso actual. |
+| [`help`](#6-help-1) | 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.
+
+```bash
+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.
+
+```bash
+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).
+
+```bash
+# 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`.
+
+```bash
+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](https://www.kopynator.com/dashboard/settings/tokens). Para subir a otro proyecto, usa el token de ese proyecto.
+
+```bash
+# 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`).
+
+```bash
+npx -y @kopynator/cli limits
+```
+
+#### 6. `help`
+Muestra la ayuda de todos los comandos.
+
+```bash
+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):
 
 ```json
 {
@@ -66,3 +238,5 @@ The `init` command creates a `kopynator.config.json` file in your root:
   "mode": "local"
 }
 ```
+
+Para entornos de CI sin fichero de configuración, define `KOPYNATOR_API_KEY` (y opcionalmente `KOPYNATOR_BASE_URL`).