🚀 Lara Cli – A Powerful CLI Tool for Instant i18n Localization

Lara Cli automates translation of your i18n files with a single command, preserving structure and formatting while integrating with a professional translation API. Given a source language, it translates your content to selected target languages based on your source i18n files.

Supports multiple file formats including JSON, PO (gettext), TypeScript, Vue I18n single-file components, Markdown and MDX files, Android XML string resource files, Xcode localization files (.strings, .stringsdict, .xcstrings), and plain text (.txt) files. See Supported Formats for details.

📑 Table of Contents

• Installation
• Setting Up Your Project
• Local Development Setup
• Technology Stack
• Supported Locales
• Usage Metrics
• Documentation

Installation

Requirements

• Node.js v18 or higher

Install via npm

The easiest way to get started is to install Lara CLI globally via npm:

npm install -g @translated/lara-cli

Once installed, you can use it from any directory:

# Get help with available commands
lara-cli --help

# Initialize a new Lara project
lara-cli init --help

# Translate your localization files
lara-cli translate --help

Setting Up Your Project

Add Your Credentials to .env

Create a .env file (or add the following lines to an existing .env) in the project where you want to run translations.

💡 Tip: If you don't have API keys yet, visit Lara's API key documentation.

LARA_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
LARA_ACCESS_KEY_SECRET=<YOUR_ACCESS_KEY_SECRET>

Replace the placeholders with your actual credentials.

🔑 Need to update credentials? If your API keys expire or need updating, run lara-cli init --reset-credentials to safely update them in your .env file.

Initialize Your Project

In your project directory, run:

lara-cli init

This will start the interactive initialization process.

The CLI will automatically detect your localization directories and target locales from your existing project files, then guide you through a few questions. These will be used to generate the configuration file: lara.yaml.

Key features:

• 🔍 Auto-detection: Scans your project for existing locale files and automatically suggests target locales
• 📊 Smart display: For enterprise projects with many locales, uses formatted tables for better readability
• ⚙️ Flexible configuration: Choose detected locales or manually add/remove as needed
• 🎯 Project instructions: Optionally provide instructions to improve translation quality (e.g., tone, style, terminology)

Providing project instructions (optional but recommended):

During initialization, you can provide instructions to help improve translation quality. Instructions guide the translation service on tone, style, and terminology. This is especially useful for:

• Tone requirements (formal, casual, professional, friendly)
• Domain-specific terminology (medical, legal, technical, etc.)
• Style preferences (concise, creative, detailed)

Providing glossaries (optional but recommended):

Lara's glossary system lets you define exactly how specific terms should be translated, across any text or document. Whether you work with technical terms, product names, or recurring brand phrases, glossaries are your best tool to ensure consistency and precision.

💡 Tip: For more information about glossaries, visit Lara's Glossary documentation.

Translate Your Files

To translate your files into the target locales, run:

lara-cli translate

That's it – you're ready to go!

📖 Documentation: For detailed information about commands, see Init Command and Translate Command.

Local Development Setup

If you want to contribute to Lara CLI or run it from source, follow these steps.

Requirements

• Node.js v18 or higher
• pnpm v8 or higher

1. Clone the repository

git clone https://github.com/translated/lara-cli.git

2. Navigate to the cloned repository

cd lara-cli

3. Install dependencies and build

Note: This project uses pnpm. If you don't have it installed, run: npm install -g pnpm. Verify the installation with pnpm -v before proceeding with the following commands.

pnpm install
pnpm run build

4. Setup pnpm global bin directory (first time only)

pnpm setup

This command configures your shell to add the pnpm global bin directory to your PATH. After running it, you'll see output similar to:

Appended new lines to /Users/<username>/.zshrc

Next configuration changes were made:
export PNPM_HOME="/Users/<username>/Library/pnpm"
case ":$PATH:" in
  *":$PNPM_HOME:"*) ;;
  *) export PATH="$PNPM_HOME:$PATH" ;;
esac

Add these lines to your shell profile (.zshrc, .bashrc, etc.) or restart your terminal to apply the changes. This ensures you can run globally installed pnpm packages.

5. Link globally

pnpm link --global

Note: If you experience an error like ERR_PNPM_NO_GLOBAL_BIN_DIR, you may need to manually copy and paste the lines added by pnpm setup into your shell profile. After doing so, restart your terminal or source your profile file, and you should be able to proceed.

After running this command, the project will be successfully linked to the pnpm global library. You should see a response similar to:

/Users/username/Library/pnpm/global/5:
+ lara-cli version <- ../../../../Projects/translated/lara-cli

6. Development Complete - Use anywhere

Now that Lara CLI is linked globally, you can use it from any directory on your system:

# Get help with available commands
lara-cli --help

# Initialize a new Lara project
lara-cli init --help

# Translate your localization files
lara-cli translate --help

Note: After making changes to the source code, run pnpm run build to update the global command.

Technology Stack

Lara CLI is built with modern technologies to ensure reliability, performance, and maintainability:

• TypeScript - For type safety and developer experience
• Commander.js - For CLI argument parsing and command structure
• Zod - For robust schema validation
• Inquirer.js - For interactive command-line user interfaces
• Lara Translation API - For high-quality, context-aware translations

The codebase follows a modular architecture with clear separation of concerns, making it easy to extend and maintain.

Supported Locales

Lara CLI supports translations using different locale codes, following two main standards:

See the full list of supported locales.

Usage Metrics

Lara CLI reports usage metrics so we can see where people get stuck between installing it and translating something. What it records is whether setup and translation succeeded, with timings, volumes, which command ran, the CLI version, your platform and Node version, whether it ran on CI, and your Lara account id — the same one shown on your account.

What is never sent: your source or translated text, file names or paths, your configuration, or your credentials.

Events are saved locally and sent in one batch when the command finishes; anything left over rides along with the next command's send. If the metrics backend is slow or unreachable the CLI behaves exactly as it does today: the send is bounded to two seconds and whatever could not be delivered simply waits for the next run. Only one process flushes a shared queue at a time. Delivery retries reuse the same eventId; the ingestion backend must deduplicate by that id because a server can accept a batch even if its response never reaches the CLI.

auth_success represents the first verified authentication for a Lara account in the CLI channel. The CLI keeps one pending milestone across commands and remembers it after ingestion acknowledges it. Repeating init, translating again or rotating an API key for the same account does not create another milestone. Each command still records its own call_success or call_error; auth_fail remains a diagnostic event for failed authentication attempts.

sessionId groups commands from the same account on the same machine, including across projects. Each command renews the session; 30 minutes without activity starts a new one. Switching accounts also starts a new session. Events within a command keep the same session, including during a long translation, and retries retain the session recorded when the event was created.

The activation event id is stable for an account/channel across installations. The backend must deduplicate this id (and historical activation events by account/channel) to keep the funnel unique across machines or after local state is deleted.

The first run that records anything prints a one-line notice on stderr saying so, once per machine.

To turn it off, use no-trace mode. The switch that keeps your content out of Lara's logs keeps the run out of these metrics too — one answer instead of two:

lara-cli translate --no-trace          # this run only

# lara.yaml — every command run in this project
noTrace: true

DO_NOT_TRACK=1 in the environment does the same, and is the way to opt out of a run that has neither a config file nor a flag.

With any of them, nothing is recorded and no file is written — not even the installation id — and whatever an earlier run had left queued is deleted. Only 0, false and an empty value are read as "leave it on"; anything else turns it off.

Documentation

For detailed documentation on using Lara CLI:

Commands

• Init Command - Initialize your project
• Translate Command - Translate your files
• Memory Command - List, create, update, delete Translation Memories; add/delete translations; import TMX
• Glossary Command - List, create, update, delete Glossaries; add/delete entries; import CSV

Configuration

• Configuration Overview - Configuration system overview
• Supported Formats - Supported file formats (JSON, PO, etc.)
• Locales Configuration - Configure source and target languages
• Files Configuration - Configure file paths and patterns
• Instructions - Configure translation instructions
• Translation Memories - Configure Translation Memories
• Glossaries - Configure Glossaries

Format-Specific Guides

• TS Files Guide - Complete guide for TypeScript files
• PO Files Guide - Complete guide for gettext PO files
• Vue Files Guide - Complete guide for Vue I18n single-file components
• Markdown Files Guide - Complete guide for Markdown and MDX files
• Android XML Files Guide - Complete guide for Android XML string resource files
• Xcode Strings Files Guide - Complete guide for Xcode .strings files
• Xcode Stringsdict Files Guide - Complete guide for Xcode .stringsdict plural files
• Xcode String Catalogs Guide - Complete guide for Xcode .xcstrings String Catalogs
• TXT Files Guide - Complete guide for plain text files