Update to Crowdin

{
  "description": "Guides correct usage of Crowdin CLI - the `crowdin` command that syncs localization files between a local project and Crowdin. Use whenever the user runs, scripts, or debugs `crowdin` commands, authorizes the CLI, creates or edits a crowdin.yml configuration, uploads sources, downloads translations, checks translation status, auto-translates a project, wires localization into CI/CD, or migrates scripts from CLI v4 to v5 - even if they just say \"sync translations\" or \"push strings to Crowdin\" without naming the CLI.",
  "included_files": [
    {
      "relative_path": "references/commands.md",
      "size_in_bytes": 20057
    },
    {
      "relative_path": "references/configuration.md",
      "size_in_bytes": 11123
    },
    {
      "relative_path": "references/migrating-from-v4.md",
      "size_in_bytes": 5029
    }
  ],
  "name": "crowdin-cli",
  "skill_md_contents": "---\nname: crowdin-cli\ndescription: Guides correct usage of Crowdin CLI - the `crowdin` command that syncs localization files between a local project and Crowdin. Use whenever the user runs, scripts, or debugs `crowdin` commands, authorizes the CLI, creates or edits a crowdin.yml configuration, uploads sources, downloads translations, checks translation status, auto-translates a project, wires localization into CI/CD, or migrates scripts from CLI v4 to v5 - even if they just say \"sync translations\" or \"push strings to Crowdin\" without naming the CLI.\n---\n\n# Crowdin CLI\n\nCrowdin CLI is the command-line tool for managing and synchronizing localization resources with a Crowdin project. It ships as a single self-contained binary — no Java or other runtime required.\n\nCheck what's installed with `crowdin --version`. If it prints `4.x` or a Java error, the user is on the legacy CLI — commands below still mostly apply, but see [references/migrating-from-v4.md](references/migrating-from-v4.md) for the differences.\n\nFull documentation: https://crowdin.github.io/crowdin-cli\n\n## Install\n\n```bash\nnpm install -g @crowdin/cli\n```\n\nAlso available via Homebrew (`brew tap crowdin/crowdin && brew install crowdin@5`), WinGet, Chocolatey, Docker (`crowdin/cli`), Linux package repositories, and as a standalone binary — see [references/configuration.md](references/configuration.md#installation) for every option.\n\n## Authenticate\n\nThe CLI needs an **API token** and (for most commands) a **project ID**. On a developer's machine the quickest route is:\n\n```bash\ncrowdin login\n```\n\nIt authorizes in the browser and saves the token to the identity file `~/.crowdin.yml`, where every later command — run by the user or by an agent — picks it up. No configuration file is generated or required, and Crowdin Enterprise needs nothing extra: the organization comes from the account signed in. `crowdin init` runs the same browser authorization and then generates a `crowdin.yml`; `login` is the choice when the config is written by hand or already exists. The flow finishes through a browser callback on the same machine, so when the agent's shell may be elsewhere, the user runs it in their own terminal. The browser-issued token expires after 30 days — re-run `crowdin login` when a command exits `101`. Details: [references/commands.md](references/commands.md#login).\n\nFor CI and anything long-lived, use a **personal access token** — it does not expire:\n\n- crowdin.com: create the token in **Settings → API** (`https://crowdin.com/settings#api-key`). `base_url` is `https://api.crowdin.com` (the default — no need to set it).\n- Crowdin Enterprise: create it in **Account Settings → Access Tokens**. `base_url` must be set to `https://{organization}.api.crowdin.com`.\n\nThe project ID is numeric — get it with `crowdin project list` once a token is configured (add `-i 1` while no `crowdin.yml` carries a `project_id`: validation demands one even though this command ignores it), or from the project page in Crowdin.\n\nCredentials resolve in this priority order (highest wins):\n\n1. CLI flags: `-T/--token`, `-i/--project-id`, `--base-url`, `--base-path`\n2. Identity file: `--identity <path>`, or `~/.crowdin.yml` / `~/.crowdin.yaml` if present\n3. `*_env` keys in the config file (`api_token_env: MY_VAR` reads `$MY_VAR`)\n4. Literal keys in the config file (`api_token: \"...\"`)\n5. `CROWDIN_PERSONAL_TOKEN`, `CROWDIN_PROJECT_ID`, `CROWDIN_BASE_PATH`, `CROWDIN_BASE_URL` environment variables\n\n`.env` files in the working directory are loaded automatically, so `CROWDIN_PERSONAL_TOKEN` can live there. **Never write a real token into `crowdin.yml`** if the file is committed — use `api_token_env` or the `CROWDIN_PERSONAL_TOKEN` variable instead. A committed `api_token_env` and a local `crowdin login` coexist: the unset variable contributes nothing, so the identity file supplies the token on the developer's machine and the variable supplies it in CI.\n\n## Configure — crowdin.yml\n\nCommands read `crowdin.yml` (or `crowdin.yaml`) from the current directory; override with `-c/--config <path>`. Minimal real-world example:\n\n```yaml\n\"project_id\": \"123456\"\n\"api_token_env\": \"CROWDIN_PERSONAL_TOKEN\"\n\"base_path\": \".\"\n\"preserve_hierarchy\": true\n\nfiles:\n  - source: \"/src/locales/en/**/*.json\"\n    translation: \"/src/locales/%two_letters_code%/**/%original_file_name%\"\n```\n\n- `source` is a glob for local source files (relative to `base_path`); `translation` tells Crowdin where exported translations land, using placeholders like `%two_letters_code%`, `%locale%`, `%original_file_name%`, `%original_path%`, `%file_name%`.\n- `preserve_hierarchy: true` keeps the local directory structure in Crowdin; without it, the common parent directory is stripped.\n- One `files` entry per file group; each entry can add `ignore`, `dest`, `type`, `update_option`, `labels`, `excluded_target_languages`, `languages_mapping`, and more.\n\nThe full reference — all placeholders, per-entry options, language mapping, multiple file groups — is in [references/configuration.md](references/configuration.md).\n\nBefore the first upload, verify the config instead of debugging a wrong upload after the fact:\n\n```bash\ncrowdin config lint            # validate syntax\ncrowdin config sources         # list local files matched by each source pattern\ncrowdin config translations    # list translation paths that will be produced\ncrowdin upload sources --dryrun\n```\n\n## Core workflow\n\nThe everyday cycle is: upload sources → translate → download translations.\n\n```bash\ncrowdin upload sources           # push local source files (alias: crowdin push)\ncrowdin status                   # translation & proofreading progress per language\ncrowdin auto-translate --method tm   # optional: pre-fill via TM, MT, or AI\ncrowdin download translations    # pull completed translations (alias: crowdin pull)\n```\n\nUseful variants:\n\n```bash\ncrowdin upload sources --cache               # skip unchanged files (checksum cache)\ncrowdin upload sources --delete-obsolete     # remove files from Crowdin that no longer exist locally\ncrowdin upload translations                  # import existing local translations\ncrowdin download translations -l uk -l fr    # only some languages\ncrowdin download translations --skip-untranslated-strings\ncrowdin download sources                     # pull sources back from Crowdin\n```\n\nEverything is branch-aware: pass `-b <name>` to scope upload/download/status to a Crowdin branch (create it with `crowdin branch add`).\n\n`auto-translate` (v4's `pre-translate`) applies TM (`--method tm`), machine translation (`--method mt --engine-id <id>`), or AI (`--method ai --ai-prompt <id>`), with fine-grained control: `--scope untranslated|translated|all`, `--skip-approved-translations`, `--label`/`--exclude-label`, `--replace-translations-option`, `--translation-modified-before`, and more — see [references/commands.md](references/commands.md#auto-translate).\n\n## Output for scripts and agents\n\nThe global `-o/--output` option changes any command's output format:\n\n- `-o json` — machine-readable JSON; pipe into `jq` or parse from a script\n- `-o toon` — [Token-Oriented Object Notation](https://github.com/toon-format/toon), same data as JSON at a fraction of the size; **prefer this when the consumer is an LLM**\n- `-o plain` — minimal processable text (v4's `--plain` flag)\n\nIn `json` and `toon` modes stdout carries nothing but data — no spinners, colors, or decorative messages — so output is safe to parse. When running the CLI as an agent, default to `-o toon` for lists you only need to read and `-o json` when a script must parse the result.\n\n```bash\ncrowdin file list -o json | jq -r '.[].path'\ncrowdin status -o toon\n```\n\nExit codes are stable and meaningful — branch on them rather than parsing error text:\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Validation error (bad config or arguments) |\n| 101 | Authorization error (bad/expired token) |\n| 102 | Not found |\n| 103 | Forbidden |\n| 129 | Rate limit exceeded |\n\nMutating file commands accept `--dryrun` to preview what would happen. Add `-v/--verbose` when diagnosing; `--no-progress`/`--no-colors` clean up logs in CI (json/toon modes already imply this).\n\n## Command map\n\n23 top-level commands; most have subcommands. Full option-level reference: [references/commands.md](references/commands.md).\n\n| Command | Purpose |\n|---------|---------|\n| `upload` (`push`) | Upload sources / translations per crowdin.yml |\n| `download` (`pull`) | Download translations / sources per crowdin.yml |\n| `init` | Generate crowdin.yml interactively |\n| `login` | Authorize in the browser and save the token to `~/.crowdin.yml` |\n| `status` | Translation & proofreading progress |\n| `auto-translate` | Pre-fill translations via TM / MT / AI |\n| `file` | Direct file ops without config patterns (list, upload, download, delete) |\n| `string` | Manage source strings (list, add, edit, delete; CroQL filters) |\n| `branch` | Manage branches (add, list, clone, merge, edit, delete) |\n| `task` | Create and list translation/proofreading tasks |\n| `tm` | Translation memories (list, upload, download; `list --assigned` scopes to the project) |\n| `glossary` | Glossaries (list, upload, download; `list --assigned` scopes to the project) |\n| `style-guide` | Style guides (list, download, upload, delete) |\n| `bundle` | Export bundles (list, add, download, clone, browse) |\n| `distribution` | Content distributions (add, list, edit, release) |\n| `screenshot` | Screenshots for context (list, upload, delete) |\n| `comment` | String comments and issues (list, add, resolve) |\n| `label` | Labels (list, add, delete) |\n| `language` | List project/supported languages; `--verbose` adds text direction and plural categories |\n| `project` | List, add, browse projects |\n| `config` | Validate config, preview matched sources/translations |\n| `app` | Install/uninstall Crowdin apps |\n| `context` | AI context for strings — covered by the [crowdin-context-cli](../crowdin-context-cli/SKILL.md) skill |\n\nShell completion: `source <(crowdin complete zsh)` (also `bash`, `fish`, `powershell`).\n\n## CI/CD\n\n- Store the token as a CI secret exposed as `CROWDIN_PERSONAL_TOKEN`; keep `project_id` in the committed `crowdin.yml` (it is not sensitive).\n- Typical pipeline: `crowdin upload sources` on merge to the main branch; `crowdin download translations` on a schedule or before release, followed by a commit/PR of the updated files.\n- For GitHub Actions prefer the official [crowdin/github-action](https://github.com/crowdin/github-action), which wraps this CLI — covered by the [github-action](../github-action/SKILL.md) skill.\n- The CLI never prompts when all required values are provided; a missing value fails with exit code 2 rather than hanging.\n- `crowdin status --fail-if-incomplete` exits non-zero when the project isn't fully translated — a ready-made release gate.\n\n## Related skills\n\n- [crowdin-context-cli](../crowdin-context-cli/SKILL.md) — `crowdin context download/upload` for AI context enrichment\n- [croql](../croql/SKILL.md) — CroQL expressions for `--croql` filters on string commands\n- [crowdin-api-client](../crowdin-api-client/SKILL.md) — the JS/TS API client, when a CLI command doesn't cover the need\n- [translate](../translate/SKILL.md) — drafts translations into local resource files with the project's glossary, TM and style guide, and uploads them as suggestions\n"
}