DOCSEARCHbyAlgolia
Submit Docs

Crowdin CLI

repository·main·Indexed 43 days ago

https://github.com/crowdin/crowdin-cli

An open-source command-line tool for managing and synchronizing localization resources with Crowdin projects. It supports automation, CI/CD integration, and AI agent workflows via machine-readable output formats like JSON and TOON. Key capabilities include initializing projects with `crowdin init`, uploading source files and translations, and downloading the latest translations.

Tokens
109K
Snippets
388
Records
596
Agent score
56%

What's inside Crowdin CLI

  1. Overview of Crowdin CLI

    main

    Crowdin CLI is a cross-platform command-line tool used to manage and synchronize localization resources with a Crowdin project. It is designed for automation and integration into CI/CD pipelines (like GitHub, GitLab, Jenkins, and CircleCI).

    Key capabilities include:

    • Automating source file updates in Crowdin.
    • Downloading translations to specific local directories.
    • Uploading existing translations to Crowdin.
    • Managing localization resources directly from the terminal.
    • Integrating with AI agent workflows via machine-readable output and context enrichment.

  2. Understand screenshot upload upsert behavior

    main

    The screenshot upload command follows an upsert pattern rather than a simple add. The identity of a screenshot is determined by the basename of the local file (e.g., ui/login.png and mobile/login.png are both identified as login.png).

    When re-running the command with a file that has the same name as an existing screenshot:

    • The existing image is replaced in place.
    • The screenshot's id and its position in the project are preserved.
    • This behavior makes scripted uploads idempotent.

    Warning: If multiple screenshots in your project share the same filename, only the oldest one will be updated, and a warning will be printed.

  3. Manage screenshot tags during upload

    main

    You can control how tags are handled during a screenshot upload using the --auto-tag flag:

    • Without --auto-tag (Default): Existing tags on the screenshot are preserved when the image is replaced.
    • With --auto-tag: All existing tags are removed and re-derived using OCR. Note: Manually placed or coordinate-accurate tags will be lost.

    If auto-tagging is already running for the project, the image will still be updated, but a warning will be printed instead of new tags being applied.

  4. Understand changes to source cache and hidden files

    main

    Source Cache Location

    The cache used by upload sources --cache (.crowdin/cache.json) is now resolved relative to your configured base_path rather than the current working directory. This ensures the cache stays near the files it describes.

    Hidden Files and Directories

    The ignore_hidden_files setting now ignores entire dot-directories (e.g., .github/) in addition to dot-files. If you need to upload files located within hidden directories, set ignore_hidden_files: false in your configuration.

  5. Format glossary file schemes with placeholders

    main

    When defining the scheme for CSV or XLS/XLSX glossary files, you can use specific placeholders to map columns to translation memory elements or specific column indices:

    • {language_code}: Represents a column containing translation memory elements for a specific language. Replace this with a valid language code (e.g., en, fr, es).
    • {column_number}: Represents the column index. Note that numbering is zero-based (starts from 0).

  6. Use environment variables for configuration

    main

    You can use environment variables to provide configuration values. This is useful for keeping credentials out of your version-controlled YAML files.

    Method 1: Mapping in YAML

    You can map specific environment variable names in your crowdin.yml using the _env suffix. These have lower priority than direct values in the same file.

    "project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"

    Method 2: Automatic Shell Detection

    The CLI automatically detects the following environment variables if they are set in your shell:

    Variable NameDescription
    CROWDIN_PERSONAL_TOKENPersonal Access Token for authentication
    CROWDIN_PROJECT_IDNumerical ID of the Crowdin project
    CROWDIN_BASE_URLBase URL of Crowdin server (e.g., https://api.crowdin.com)
    CROWDIN_BASE_PATHLocal path to your project directory (default: .)
    "project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path_env": "CROWDIN_BASE_PATH"
"base_url_env": "CROWDIN_BASE_URL"

  8. Understand file path relativity in Crowdin CLI

    main

    When listing or managing files, file paths are always branch-relative. This means the paths provided do not include the name of the branch specified via the -b or --branch flags.

    If you run a command without the --branch flag, the CLI will only list files that exist outside of any specific branch (i.e., files in the base/root level).

  10. Filter strings by context status

    main

    When using download, reset, or status commands, you can filter strings based on their current context state using the --status flag. Supported values are:

    • empty: Strings with no context at all.
    • ai: Strings that have AI-generated context.
    • manual: Strings that have manually entered context.

  11. Understand the E2E test suite layout

    main

    The E2E test directory is organized into helpers, fixtures, and suites. Each suite is a self-contained file that manages its own Crowdin project lifecycle:

    • beforeAll: Provisions the workspace, project, and configuration.
    • test(): Executes CLI commands in declaration order.
    • afterAll: Tears down the project and workspace.

    Directory Structure:

    • e2e/helpers/: Contains logic for env, workspace, config, cli, normalize, project, and suite management (includes unit tests).
    • e2e/fixtures/: Contains <suite>/config/crowdin.yml templates and source files (e.g., sources/).
    • e2e/suites/: Contains individual suite files, where each file owns exactly one project.

  12. Configure CLI Output Formats

    main

    Use the -o or --output flag to switch between different output modes. In machine-readable formats, stdout contains only the result, while warnings and errors are sent to stderr to ensure pipelines remain parseable.

    • text (default): Designed for humans. Includes colors, symbols, spinners, and progress bars.
    • plain: Designed for shell pipelines (e.g., grep, awk). Provides one bare line per entity, starting with the identifier, with no colors or prose.
    • json: Designed for parsers. Provides the complete result as a structured JSON document.
    • toon: Designed for AI agents. Provides the same data as json using the token-efficient TOON encoding.

    Example: Using plain output for shell processing

    crowdin file list --output plain