Commands

The Algebras CLI provides several commands to manage your localization workflow. This reference covers all available commands and their options.

Command Overview

Command	Description
`init`	Initialize or regenerate configuration
`add`	Add a language to your project
`translate`	Translate source files to target languages
`update`	Update existing translations
`ci`	CI-friendly check command for automated workflows
`review`	Compare translated files against the source and flag issues
`status`	Show project status and translation progress
`healthcheck`	Validate translation quality (placeholders, formatting, tags)
`configure`	Configure CLI settings
`glossary push`	Upload glossary terms from a CSV/TSV/XLSX file

Every command accepts a global -f/--config-file <path> option (before the subcommand) to use a config file other than .algebras.config, e.g. algebras -f .algebras-fr.config translate.

init

Initialize or regenerate your Algebras configuration.

Usage

algebras init [options]

Options

--force - Force initialization even if a config file already exists
--verbose - Show detailed information about locale detection
--provider <provider> - Set the default provider (currently only algebras-ai is supported)

Examples

# Initialize new project
algebras init

# Regenerate existing configuration
algebras init --force

# Initialize with verbose detection output
algebras init --verbose

What it does

Auto-detects locale files in your project (common src/locales, i18n, public/locales, messages, etc. patterns) and infers languages from filenames/directories
Creates a .algebras.config file with the detected languages and source file mappings
Defaults to algebras-ai as the provider
Warns if ALGEBRAS_API_KEY is not set

Language selection is automatic, not interactive — init does not prompt you to pick languages. Use algebras add afterward to add more.

add

Add a single language to your project configuration.

Usage

algebras add <language>

add takes exactly one language code per invocation — to add several languages, run it multiple times.

Examples

# Add a language
algebras add es

# Add several languages
algebras add fr
algebras add de

Supported Language Codes

Common language codes include:

es - Spanish
fr - French
de - German
pt_BR - Brazilian Portuguese
zh_CN - Simplified Chinese
ja - Japanese
ko - Korean
ru - Russian
ar - Arabic

There is currently no algebras remove command — remove a language by deleting its entry from the languages list in .algebras.config.

translate

Translate source files to target languages.

Usage

algebras translate [options]

Options

--language, -l <code> - Translate only the specified language
--force[=<keys>] - Force translation even if files are up to date. Pass it bare to force everything, or with a comma-separated key list (e.g. --force "key1,key2") to force only those keys
--only-missing - Only translate keys that are missing in the target files
--ui-safe - Ensure translations don’t exceed the original text length
--verbose - Show detailed logs of the translation process
--batch-size <number> - Override the batch size for this run. Without this flag, the value comes from batch_size in .algebras.config (5 in a project created by algebras init), falling back to ALGEBRAS_BATCH_SIZE, then a hardcoded 20
--max-parallel-batches <number> - Override the maximum number of parallel batches (default: 5)
--glossary-id <id> - Use a specific glossary for translation
--prompt-file <file> - Use a custom prompt loaded from a file
--regenerate-from-scratch - Regenerate target files from scratch instead of updating them in place
--sync-batch - Use the legacy synchronous batch translation endpoint instead of the default async submit+poll endpoint
--no-cache - Bypass cached translations (API-side and local cache) and force fresh results

Examples

# Basic translation
algebras translate

# Only one language
algebras translate --language fr

# UI-safe translation
algebras translate --ui-safe

# Use custom batch size
algebras translate --batch-size 10

# Use a glossary
algebras translate --glossary-id glossary-123

# Custom prompt from a file
algebras translate --prompt-file custom-prompt.txt

# Force re-translation of specific keys only
algebras translate --force "common.title,common.subtitle"

# Bypass the translation cache
algebras translate --no-cache

update

Update existing translations based on source file changes.

Usage

algebras update [options]

Options

--language, -l <code> - Update only the specified language
--full - Translate the entire file, not just missing/outdated keys
--only-missing - Only translate keys that are missing, and skip git-based outdated-key validation
--ui-safe - Ensure translations don’t exceed the original text length
--verbose - Show detailed logs of the update process

If neither --full nor --only-missing is passed, update defaults to updating missing and outdated keys (using git to detect changed source lines). update does not accept translate’s batch-processing, glossary, or prompt options.

Examples

# Update missing/outdated translations
algebras update

# Full re-translation of every key
algebras update --full

# Update only missing keys, skip git validation
algebras update --only-missing

# UI-safe update
algebras update --ui-safe

ci

CI-friendly command that checks translation completeness without translating. It always uses git-based validation unless --only-missing is passed, and exits non-zero if issues are found — no separate --fail-on-error flag is needed.

Usage

algebras ci [options]

Options

--language, -l <code> - Check only the specified language
--verbose - Show detailed logs of the check process
--only-missing - Only check for missing keys; skip git validation for outdated keys

Examples

# Fail the build if translations are missing or outdated
algebras ci

# Only check for missing keys
algebras ci --only-missing

review

Compare each target language’s files against the source language and flag missing keys, extra keys, type mismatches, and suspiciously short/long translations (a simple length-ratio heuristic).

Usage

algebras review [options]

Options

--language, -l <code> - Review only the specified language. If omitted and more than one target language is configured, you’ll be prompted to pick one.

Examples

algebras review --language fr

status

Show translation progress and configuration information.

Usage

algebras status [options]

Options

--language, -l <code> - Show status only for the specified language

Output

For each configured target language, status prints the number of translated keys vs. expected keys (with percentage), any outdated keys, and the file completion count. It also validates your configured language codes against the API (when ALGEBRAS_API_KEY is set) and warns about codes the API doesn’t recognize.

healthcheck

Validate translation quality — checks for placeholder/variable mismatches, unbalanced HTML/XML tags, formatting differences, and other structural issues between source and target strings. Exits with a non-zero status if errors are found, making it usable in CI alongside ci.

Usage

algebras healthcheck [options]

Options

--language, -l <code> - Check only the specified language
--format <console|json> - Output format (default: console)
--verbose - Show detailed information

Examples

algebras healthcheck
algebras healthcheck --language de --format json

configure

View or change CLI settings stored in .algebras.config. Run with no options to print the current configuration.

Usage

algebras configure [options]

Options

--provider <provider> - Set the API provider (currently only algebras-ai)
--model <model> - Set the model for the provider (stored in config; not used by the algebras-ai provider today)
--path-rules <rules> - Set legacy path rules (comma-separated patterns)
--batch-size <number> - Set the default batch size for translation processing
--max-parallel-batches <number> - Set the default maximum number of parallel batches
--glossary-id <id> - Set the default glossary ID for translations
--prompt <text> - Set a default prompt for translations
--normalize-strings <true|false> - Enable/disable string normalization (removes escaped characters like \')

Examples

# Show current configuration
algebras configure

# Set batch size
algebras configure --batch-size 15

# Set multiple options
algebras configure --batch-size 10 --max-parallel-batches 3

# Set default prompt
algebras configure --prompt "Translate to {target_language} maintaining a professional tone"

# Enable string normalization
algebras configure --normalize-strings true

glossary push

Upload glossary terms from a CSV, TSV, or XLSX file, creating a new glossary in the process.

File Format

The file’s first column must be a Record ID (a unique identifier for the term), followed by one column per language, using the language code as the header. Each row is a term, with its translation in each language column:

Record ID,en,fr,de
1,Submit,Envoyer,Absenden
2,Cancel,Annuler,Abbrechen

Empty cells are skipped (not uploaded as blank terms)
Rows with a missing Record ID, or with a different column count than the header, are skipped with a warning
Terms longer than 1000 characters are truncated automatically; --max-length applies a stricter, configurable limit on top of that (default: 255)
TSV files use the same layout with tabs instead of commas

Usage

algebras glossary push <file> --name <name> [options]

Options

--name <name> - Name of the glossary to create (required)
--batch-size <number> - Number of terms to upload per request (default: 100)
--debug - Log all requests before sending
--rows-ids <ids> - Comma-separated list of row numbers or record IDs to include (upload a subset)
--max-length <number> - Maximum allowed term length; longer terms are skipped (default: 255)

Examples

# Upload a full glossary
algebras glossary push terms.csv --name "Product Glossary"

# Upload only specific rows
algebras glossary push terms.xlsx --name "Product Glossary" --rows-ids "1,2,5"

# Use the resulting glossary in translation
algebras translate --glossary-id <glossary-id-from-output>

Environment Variables

The CLI respects these environment variables:

ALGEBRAS_API_KEY - Your API key (required for translation)
ALGEBRAS_BASE_URL - Custom API base URL (default: https://platform.algebras.ai)
ALGEBRAS_BATCH_SIZE - Default batch size, used when not set in config or via --batch-size
ALGEBRAS_MAX_PARALLEL_BATCHES - Default max parallel batches, used when not set in config or via --max-parallel-batches

Global Options

algebras --version - Show CLI version
algebras <command> --help - Show help for any command
algebras -f <path> <command> - Use a custom config file instead of .algebras.config

Note that --verbose is defined per-command (available on init, translate, update, ci, and healthcheck), not as a single global flag.

Command Workflow Examples

Basic Translation Workflow

# 1. Initialize project
algebras init

# 2. Add languages
algebras add es
algebras add fr

# 3. Translate files
algebras translate

# 4. Check status
algebras status

Advanced Workflow with Custom Settings

# 1. Configure defaults
algebras configure --batch-size 10 --max-parallel-batches 2

# 2. Translate with UI-safe mode
algebras translate --ui-safe --glossary-id tech-terms

# 3. Update only missing translations
algebras update --only-missing

CI/CD Integration

# In your CI pipeline
algebras ci --only-missing

Troubleshooting Commands

Check Configuration

algebras configure
algebras status

Validate Setup

algebras init --force
algebras status

Test Translation

algebras translate --verbose

Next Steps

Advanced Features - Explore glossaries, batch processing, and Git integration
Troubleshooting - Common issues and solutions
Configuration - Detailed configuration options