i18n & l10n CLI

Localization automation is, at its core, the process of making the localization process faster and more agile by automating specific tasks (i.e., string management and translation, format conversions, delivery of localized files etc.) that otherwise would consume a lot of time to complete.

Localazy is here to help product teams and single developers automate the localization of their projects.

You might be interested in:

• How to prepare your application for i18n & l10n
• Localization automation - language as a product or service?

Localazy will streamline your localization process, serve as a source of truth for your translations, and facilitate collaboration with your team and translators.

The main benefits of Localazy for product managers include:

• Less back and forth between team member tasks
• Simply defined process, clear visibility of the progress, and the definition of done
• Automated distribution and change management
• Less time spent on managing translators

Localazy offers over 50 integration options, including native plugins for Figma, Strapi & Zapier. You can also integrate your product with Localazy via API, CLI, and mobile SDKs for Android and iOS.

You can use Localazy to offload the translation work from your team completely. Thanks to the built-in Continuous Localization services, you can get your project translated by professionals and don’t have to worry about any task handling.

Learn how proactive professional translation services by Localazy work.

Localazy CLI delivers advanced capabilities that go beyond basic translation management:

• Format conversion and type remapping let you migrate between file formats or maintain different output formats without writing custom scripts
• Full branching support with conflict resolution helps you maintain translations across feature branches, white-label variants, and product versions
• Dynamic configuration with runtime variables enables flexible workflows across different environments and build configurations
• Built-in validation prevents localization issues from reaching production by catching missing translations, invalid formats, and plural form mismatches
• Advanced plural form handling automatically manages complex language rules without requiring custom handling code
• Incremental updates and CDN integration ensure efficient delivery of translations at scale
• Integration with CI/CD platforms like GitHub, GitLab or Bitbucket lets you automate localization as part of your existing workflow
• Simulation mode helps you validate changes before execution

Whether you’re working on a small app or a complex enterprise system, Localazy CLI provides the tools you need to handle localization efficiently while maintaining code quality.

Localazy CLI is a robust command-line interface tool designed for handling software localization workflows. It serves as a bridge between your development environment and Localazy’s translation platform.

The CLI handles both uploading source files for translation and downloading completed translations back into your project structure. It supports complex localization scenarios like plurals, string arrays, and nested key structures.

Beyond basic file operations, it provides features for versioning (through Release Tags), project branching, and format conversions. The CLI integrates with CI/CD pipelines and can be automated as part of your build process, making it particularly valuable for teams practicing continuous deployment.

Localazy CLI supports an extensive range of file formats commonly used in software development:

• Mobile: Android XML, iOS strings/stringsdict, Flutter ARB
• Web: JSON, YAML, JavaScript, PHP
• Desktop: Qt TS, RESX, Java Properties
• Generic: XLIFF, PO/POT, CSV, Excel, OpenOffice
• Documentation: Plain text, Markdown

Each format support includes advanced features like:

• Plural form handling appropriate to the format
• Array support where applicable
• Structured data preservation
• Format-specific metadata handling

Most formats also support custom features that can be enabled via configuration flags.

The configuration process centers around the localazy.json file in your project root.

An example configuration includes:

{
    "writeKey": "your-write-key",
    "readKey": "your-read-key",
    "upload": {
        "type": "json",
        "files": {
            "pattern": "src/**/locales/*.json",
            "path": "${path}",
            "file": "${file}"
        }
    },
    "download": {
        "files": "src/locales/${lang}/${file}"
    }
}

The configuration supports variables, conditions, transformations, and format-specific features. You can also include group definitions for organizing different sets of files and rules for handling special cases.

Localazy CLI provides several methods for importing existing translations:

• Use autodetectLang variable to automatically detect language from file paths/names
• Explicitly specify languages in your configuration
• Use groups to separate source language uploads from existing translations

Basic configuration can look like this:

{
    "upload": {
        "files": [
            {
                "pattern": "src/locales/en/*.json",
                "lang": "inherited"
            },
            {
                "group": "existing",
                "pattern": "src/locales/*/*.json",
                "excludes": ["src/locales/en/*.json"],
                "lang": "${autodetectLang}"
            }
        ]
    }
}

This setup lets you run localazy upload for regular source updates and localazy upload existing for one-time import of existing translations.

Yes, absolutely. You can have multiple files in different folders uploaded to the same project.

You can include files by their exact path or by using standard path wildcards ? (single character), * (anything except path separator), ** (anything including path separators).

You can control files you want to upload with exclusion rules and conditions.

Example:

"upload": {
    "type": "json",
    "files": "modules/**/en.json"
  }
 
}

The above configuration will scan for files named en.json in all subfolders of the modules folder.

As a developer, connecting to your Localazy project via Localazy CLI requires you to provide your unique readKey and writeKeyto authorize upload and download operations.

You need to have the Owner role in the project to access your unique access keys. Then, navigate to the project and open the left menu to find Settings ->Access Keys

Learn more in the Localazy CLI: Authorization

The Localazy CLI is a powerful tool designed to automate the process of uploading and downloading translation files in almost any project. If you encounter any issues or questions that are not addressed in the documentation, there’s no need to worry as we’re happy to help you to overcome these challenges.

Simply reach out to us through our chat, and we’ll make every effort to assist you promptly. Alternatively, you can send an email to team@localazy.com, providing your configuration details and a clear description of your goal. We will respond as quickly as possible to ensure your seamless experience with Localazy.

Localazy CLI fits directly into your existing build pipeline without requiring you to change your project structure or source code. You configure it through a localazy.json file in your project root, then call localazy upload and localazy download as steps in your pipeline.

The typical pattern is straightforward: upload runs when new source strings are merged into your development branch, giving translators time to work while you continue building. Download runs when you’re ready to cut a release, pulling in all approved translations automatically.

For GitHub Actions, GitLab CI, and Bitbucket Pipelines, the setup follows the same principle. Store your LOCALAZY_WRITE_KEY and LOCALAZY_READ_KEY as repository secrets, reference them in your pipeline configuration, and define the trigger conditions. For example, uploading only when the source locale file changes, and downloading only on tagged releases.

# GitLab CI example — upload on merge to staging
localazy-upload:
  image:
    name: localazy/cli:latest
  rules:
    - changes:
        - src/**/locale/en.json
      if: '$CI_COMMIT_BRANCH == "staging"'
  script:
    - localazy upload -w $LOCALAZY_WRITE_KEY -r $LOCALAZY_READ_KEY

The CLI is available as a native binary for all major operating systems, as a Java JAR, and as a Docker image, so it works in any CI environment. Once set up, the pipeline handles translation synchronization automatically — developers commit code, translators work in the Localazy dashboard, and localized builds are produced without anyone managing files manually.

The CLI and the SDKs solve different problems, and in many projects, you’ll use both.

The CLI handles the pipeline side: uploading source strings to Localazy and downloading completed translations back into your build. It works at the file level — it reads your Android .xml or iOS .strings/.xcstrings files, syncs them with Localazy, and writes the translated versions back to disk as part of your build process. There’s no library added to your app, and no runtime dependency. For teams that want clean separation between localization tooling and the app itself, the CLI-only approach is a solid choice.

The Android Gradle plugin and iOS Swift SDK go a step further by enabling over-the-air (OTA) translation updates. Once the SDK is integrated into your app, new or corrected translations can be delivered directly to users through Localazy’s CDN without requiring an app store update or a new release. The SDK handles caching, locale detection, and only downloads what’s changed. For mobile teams that need to fix translation errors quickly or launch new languages between releases, this is a significant practical advantage.

The tradeoff is integration depth. The SDK adds a lightweight runtime dependency to your app and requires initialization in your application class (Android) or app delegate (iOS). The CLI requires no app-level changes at all.

A common setup: use the CLI in your CI/CD pipeline to keep source strings and translations in sync during development, and integrate the SDK for production OTA delivery. If you build for both Android and iOS, the CLI can manage both platforms from a single workflow, handling format conversion automatically between the two.

Branching in Localazy lets you maintain separate translation states for different versions of your software — for example, a feature under active development, a stable release, or a white-labeled variant. Each branch is a copy of the main project, including its glossary, screenshots, and contributor permissions. From the CLI, you create and switch between branches using the --branch flag, which can be added to upload, download, cdn, and tag commands. This means your pipeline for a feature branch uploads strings to that branch’s translation state without affecting main.

# Create a new branch from main
localazy branch create main feature/payments

# Upload source strings to the feature branch
localazy upload --branch feature/payments

# Download translations for the feature branch
localazy download --branch feature/payments

When the feature is ready to ship, you merge it back. If there are conflicts, such as the same key being edited in both branches, the CLI surfaces them through localazy branch conflicts, and you can handle them manually or apply an automatic resolution strategy.

One thing to highlight about pricing: each branch counts against your source key limit, but Localazy only counts the “affected” keys inside the branch, not a full copy of every key.

This workflow maps well to how most teams already use Git. Your Localazy branching structure can mirror your code branches, keeping translation states in sync with development without translators ever needing to know which branch they’re working on — you control that at the CI level.

Release Tags let you control exactly which version of translations gets served to users in each environment, independent of what translators are actively working on.

By default, every change published in Localazy becomes part of the latest tag automatically, updated within 15-minute intervals. This is useful during development, but in production you typically don’t want live translator edits to reach users immediately. Release Tags solve this by creating a named snapshot of your project’s current translation state.

# Publish current translations as a staging release
localazy tag publish staging

# When ready, promote staging to production
localazy tag promote staging production

# Or tag a specific version
localazy tag promote staging v2.1

Once a tag is published, its content stays fixed unless you explicitly update it. Translators can continue working, and new strings can be added without affecting what production serves. When you’re confident in the new state, promote staging to production with a single command.

In a CI/CD pipeline, the pattern works like this: your upload step pushes new source strings to Localazy on merge; translators translate in the dashboard; your release pipeline downloads using the -t flag to pull a specific tag, then promotes it if tests pass.

# Download translations pinned to the production tag
localazy download -t production

This gives you a clean separation between “translations being worked on” and “translations shipped to users,” with no manual file management involved.