The localazy translate command provides on-demand, realtime AI translation directly from the command line. Unlike the batch operations, it does not modify any phrases stored in your project — it just returns translations synchronously so you can use them in scripts, build pipelines, or one-off tasks.

This is the same translation technology that powers Localazy AI in the editor and integrations, exposed for ad-hoc use without requiring a separate public API token.

Authorization #️⃣

AI translation is restricted to project owners. The command uses the standard writeKey configured for the CLI — managers and other roles will be rejected with an authorization error.

See Authorization for details on how to configure the key.

Context

This command automatically uses the project’s style guide, glossary and other contextual tools.

Translate a single text #️⃣

The simplest invocation translates a piece of text from one language to another:

localazy translate --from en --to cs --text "Hello, world!"

The translated text is printed to standard output. This makes it easy to pipe into other tools or capture into shell variables:

TRANSLATED=$(localazy translate --from en --to de --text "Welcome")

Translate multiple items from a JSON file #️⃣

For bulk on-demand translation, prepare a JSON file with the items to translate and pass it via --input:

localazy translate --from en --to cs --input items.json

The input file must be a JSON array of items. The minimal item only needs key and source:

[
  {
    "key": "greeting",
    "source": "Hello, world!"
  },
  {
    "key": "farewell",
    "source": "Goodbye!"
  }
]

The output is a JSON object mapping each key to its translation, pretty-printed by default:

{
  "greeting": "Ahoj, světe!",
  "farewell": "Sbohem!"
}

Use --compact to emit a single-line JSON object instead — useful when the output is consumed by another program:

localazy translate --from en --to cs --input items.json --compact

Plurals #️⃣

The source of an item can be either a string (for regular phrases) or an object whose keys are CLDR plural categories (zero, one, two, few, many, other):

[
  {
    "key": "item_count",
    "source": {
      "one": "%d item",
      "other": "%d items"
    }
  }
]

The translation in the response will follow the same shape — a string for singles, an object keyed by the target language’s CLDR plural categories for plurals.

Item metadata #️⃣

Each item in the input file accepts optional fields that help the AI engine produce better translations:

Field Description
key The identifier of the text that can be used as a source for the context. E.g., button-label, etc.
comment Free-form context for the translator/engine — e.g. “Use imperative verb”.
lengthLimit Maximum number of characters the translation should not exceed.
file The source file the phrase comes from. Serve as additional context.

Example with metadata:

[
  {
    "key": "greeting",
    "source": "Hello, world!",
    "comment": "Should be informal",
    "file": "strings.xml",
    "lengthLimit": 50
  }
]

Command-line options #️⃣

Option Default Description
--from LOCALE required Source language locale code (e.g. en, en-US).
--to LOCALE required Target language locale code (e.g. cs, de, fr).
--text TEXT (or -t) — Translate a single piece of text. Mutually exclusive with --input.
--key KEY text Key to use for the translated text when --text is provided.
--input FILE — Path to a JSON file with items to translate. Mutually exclusive with --text.
--compact false Output a single-line JSON object instead of pretty-printed (only meaningful with --input).
--branch NAME project default Run the translation against a specific branch.

You must provide either --text or --input — invoking the command without one of them is an error.

Limits and rate limiting #️⃣

The realtime translation endpoint is subject to per-project rate limits and per-request size limits to prevent abuse. If you need to translate large amounts of content as part of your project workflow, please contact us.

Examples #️⃣

Translate a literal string and print the result:

localazy translate --from en --to cs --text "Hello, world!"

Translate a batch from a file and store the result as JSON:

localazy translate --from en --to de --input src.json --compact > de.json