Q: Localazy CLI is not working on macOS Big Sur and later

After upgrading to macOS Big Sur , there’s a chance you may run into an issue with executing Localazy CLI. This is usually caused by incorrect configuration of brew package manager. (Note that this doesn’t apply to binaries downloaded directly from our website, they should be working fine.) The symptoms look like this, the process is killed without any further output. To resolve the issue, go to App Store -> Updates and make sure, there’s no update available for Xcode. If yes, click “UPDATE” and wait for it to finish. After the update, try to run brew doctor and read the output carefully. There could be a warning about outdated CLT and suggested fix. Let’s run the commands in the specified order and confirm all dialogues that might appear. softwareupdate --all --install --force , sudo rm -rf /Library/Developer/CommandLineTools sudo xcode-select --install Upgrade Localazy CLI to the latest version by running brew upgrade localazy/tools And that’s all! You can now verify that Localazy CLI is working again with the localazy -h command.

Question 1

Is it possible to download the files to their original locations?

Accepted Answer

To download translations to their original locations, you can follow these steps. First, in the localazy.json configuration file and go to the download section. In this section, configure where you want to download your translations.

For a smoother process, ensure that you include the “path” parameter during the upload and use the same variable in the download section. Here’s an example of how to do it:

"upload": {
  "files": [
    {
      "pattern": "src/**/locale/en.ts",
      "lang": "inherited",
      "path": "${path}"
    }
  ]
},

"download": {
  "files": [
    {
      "output": "${path}/${lang}.ts"
    }
  ]
}

By setting the “path” parameter correctly, the translations will be downloaded to the respective locations specified in your localazy.json configuration file.

Question 2

Localazy CLI is not working on macOS Big Sur and later

Accepted Answer

After upgrading to macOS Big Sur, there’s a chance you may run into an issue with executing Localazy CLI. This is usually caused by incorrect configuration of brew package manager. (Note that this doesn’t apply to binaries downloaded directly from our website, they should be working fine.)

The symptoms look like this, the process is killed without any further output.

To resolve the issue, go to App Store -> Updates and make sure, there’s no update available for Xcode. If yes, click “UPDATE” and wait for it to finish.

After the update, try to run brew doctor and read the output carefully. There could be a warning about outdated CLT and suggested fix.

Let’s run the commands in the specified order and confirm all dialogues that might appear.

softwareupdate --all --install --force,
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

Upgrade Localazy CLI to the latest version by running brew upgrade localazy/tools

And that’s all! You can now verify that Localazy CLI is working again with the localazy -h command.

Question 3

How can I convert different localization file formats?

Accepted Answer

In the File Management section of Localazy, when downloading your files, you can select the desired format and download your strings in any of the available file formats.

Format Conversions feature is also an integral part of the Localazy CLI tool, so if you want to automate format conversions, you will need to install Localazy CLI on your preferred platform.

Read the article: How to convert localization files into different formats?

Note: Format Conversions are available only as a part of the Professional plan

Question 4

What is the maximum possible length of translation text?

Accepted Answer

There is no hard limit at the moment, but it’s recommended to keep the size of each individual item under 4kB. This corresponds to 4,000 characters encoded as UTF-8 and 2,000 characters encoded as UTF-16. Uploading longer texts won’t yield any errors, but might get refused by some external translation engines integrated in Localazy.

Question 5

Why are the recent changes or new translations not downloaded?

Accepted Answer

If you come across this issue, it is likely because you have exceeded your account’s source key limit or the changes you made haven’t been published yet. To resolve this, please go to the Billing section of your account to check your source key limit and consider upgrading if necessary. Additionally, you can visit your Project Activity Stream to verify if the project has been published.

Question 6

How can I upload POT and download PO files with Localazy CLI?

Accepted Answer

When using Localazy CLI, setting up a comfortable POT/PO workflow requires some special settings, but is completely possible. Usually the source language file has a different format (POT) than files with translated strings in your project (PO).

We recommend setting two different rules for uploading:

Upload your messages.pot file with "type": "pot" and also provide the file attribute to be sure that the filename is, in ideal case, something like messages.po to properly link your POT file to a PO file that is used for your source language internally by Localazy.
To upload existing translations inside PO files, use "type": "po" and provide the same file attribute again.

Example configuration #️⃣

Your upload configuration should then look like this:

"files": [
  {
    "type": "pot",
    "pattern": "source/messages.pot",
    "file": "message.po"
  },
  {
    "group": "existing-translations"
    "type": "po",
    "pattern": "translations/*/messages.pot",
    "file": "message.po"
  }
]

Question 7

I have trouble with my CLI configuration. Can you help me?

Accepted Answer

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.

Question 8

How to get rid of quotation marks after conversion from JSON to Android XML?

Accepted Answer

Suppose you have a project where the source file is a JSON file with a row in the format:

"about.moreButton": "Learn more on our website",

When using the Localazy CLI to import to Android with Format Conversions (or when you just try to export the JSON file to Android XML inside the Localazy web platform), you might notice that the format is:

<string name="about_moreButton">"Learn more on our website"string>

Now, you might think you should delete those start and end quotation marks in the body of the XML row to achieve this result:

<string name="about_moreButton">Learn more on our websitestring>

However, you can keep the quotation marks in the Android XML file because it’s a supported construct used to correctly encode white characters that would otherwise be lost in all cases. Quotation marks ensure that the exact form of your strings is preserved after conversion.

In actual use, the text will render correctly on the device.

More information can be found on the Android Developers website: String Resources

Question 9

Where can I find my access keys?

Accepted Answer

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

Question 10

Is it possible to manage multiple folders in one Localazy project?

Accepted Answer

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.

Question 11

What exactly is Localazy CLI and what are its core capabilities?

Accepted Answer

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.

Question 12

How do I set up my Localazy CLI configuration?

Accepted Answer

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.

Question 13

What's the best way to handle existing translations with Localazy CLI?

Accepted Answer

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.

Question 14

How can Localazy CLI integrate into my CI/CD workflow?

Accepted Answer

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.

Question 15

Should I use Localazy CLI or Android/iOS SDK for mobile app localization?

Accepted Answer

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.

Question 16

How do I use Localazy CLI with Branching?

Accepted Answer

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.

Question 17

How do I use Localazy CLI with Releases?

Accepted Answer

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.

CLI

💡 Enough theory, try Localazy now! 🚀