Advanced Features

The Algebras CLI offers several advanced features to optimize your localization workflow, including UI-safe translations, custom prompts, glossary management, batch processing, and Git integration.

UI-Safe Translations

The --ui-safe flag ensures that translations won’t exceed the original text length, which is crucial for maintaining consistent UI layouts.

Usage

algebras translate --ui-safe
algebras update --ui-safe

When to Use

UI strings with length constraints
Button labels and navigation items
Form field labels
Mobile app interfaces
Responsive web designs

Example

# Original: "Submit"
# UI-Safe Translation: "Enviar" (5 chars)
# Regular Translation: "Enviar formulario" (15 chars)

Custom Translation Prompts

You can provide custom prompts for more specific translation requirements.

Using Prompt Files

Create a prompt file:

echo "Translate to {target_language} maintaining a professional tone for a business application" > custom-prompt.txt

Use the prompt file:

algebras translate --prompt-file custom-prompt.txt

Using Inline Prompts

algebras translate --prompt "Translate to {target_language} using casual, friendly language"

Setting Default Prompts

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

Prompt Variables

Available variables in prompts:

{target_language} - Target language name
{source_language} - Source language name
{context} - Translation context (if available)

Glossary Management

Algebras CLI supports glossary management for consistent terminology across translations.

Creating Glossaries

Glossaries can be created through the platform, or uploaded directly from a CSV, TSV, or XLSX file using algebras glossary push:

algebras glossary push terms.csv --name "Product Glossary"

This creates a new glossary and uploads the terms in batches (100 per batch by default, adjustable with --batch-size). The command prints the new glossary’s ID, which you’ll use with --glossary-id. Other options:

--rows-ids <ids> - Upload only specific rows (comma-separated row numbers or record IDs)
--max-length <number> - Skip terms longer than this (default: 255)
--debug - Log outgoing requests before sending

Using Glossaries

algebras translate --glossary-id glossary-123

Or set it as a project default so every translate run uses it automatically:

algebras configure --glossary-id glossary-123

Glossary Benefits

Consistent terminology across translations
Domain-specific vocabulary
Brand name preservation
Technical term accuracy

Batch Processing

Optimize translation performance with batch processing settings.

Adjusting Batch Size

# Process 10 translations per batch
algebras translate --batch-size 10

Controlling Parallel Batches

# Run maximum 3 batches in parallel
algebras translate --max-parallel-batches 3

Configuring Defaults

algebras configure --batch-size 10 --max-parallel-batches 3

Performance Tips

Smaller batch sizes (5-10) for better error handling
Larger batch sizes (20-50) for faster processing
Fewer parallel batches for rate limit compliance
More parallel batches for maximum throughput

Forcing and Caching Behavior

translate normally skips files/keys that are already up to date and uses translation caching. A few flags override that behavior for specific cases:

Force Re-translating Specific Keys

# Force everything to re-translate
algebras translate --force

# Force only specific keys, leaving the rest untouched
algebras translate --force "common.title,common.subtitle"

Bypassing the Cache

# Skip both the API-side and local translation cache
algebras translate --no-cache

Useful when a previous translation was wrong and you need a genuinely fresh result rather than a cached one.

Regenerating Files From Scratch

By default, translate updates existing target files in place. To discard the existing target file and regenerate it entirely:

algebras translate --regenerate-from-scratch

Legacy Synchronous Batch Endpoint

translate submits jobs to an async submit-and-poll endpoint by default. If you need the older blocking behavior:

algebras translate --sync-batch

Git Integration

Algebras CLI automatically tracks translation changes using Git.

Automatic Git Detection

The CLI automatically:

Detects outdated keys by comparing modification times
Validates translations against source file changes
Skips unnecessary translations

Git-Friendly Commands

# Skip git validation (useful for CI)
algebras translate --only-missing

# CI-friendly check — exits non-zero if translations are missing or outdated
algebras ci

Git Workflow Integration

# 1. Make changes to source files
git add src/locales/en/
git commit -m "Update English strings"

# 2. Update translations
algebras update

# 3. Commit translation changes
git add src/locales/
git commit -m "Update translations"

String Normalization

Control how strings are processed before translation.

Enable String Normalization

algebras configure --normalize-strings true

This removes escaped characters like \' and normalizes whitespace.

Disable String Normalization

algebras configure --normalize-strings false

This preserves all characters exactly as they appear.

When to Use Each Mode

Enable normalization for:

User-facing text
Clean, readable translations
Standard localization files

Disable normalization for:

Code strings
Technical documentation
Strings with special formatting

Advanced Configuration Options

Custom API Settings

api:
  provider: algebras-ai
  model: gpt-4
  batch_size: 15
  max_parallel_batches: 2
  normalize_strings: true

Environment Variables

export ALGEBRAS_BATCH_SIZE=15
export ALGEBRAS_MAX_PARALLEL_BATCHES=2
export ALGEBRAS_BASE_URL=https://custom-api.example.com

Workflow Optimization

Incremental Updates

# Only translate missing or outdated keys
algebras update --only-missing

Selective Translation

# Translate a single language at a time
algebras translate --language es
algebras translate --language fr

Quality Assurance

# Use UI-safe mode for UI strings
algebras translate --ui-safe --glossary-id ui-terms

# Use custom prompt for technical content
algebras translate --prompt-file technical-prompt.txt

Performance Monitoring

Verbose Output

algebras translate --verbose

Shows detailed progress information including:

Batch processing status
Translation timing
Error details
Performance metrics

Status Monitoring

algebras status

Shows, per configured language:

Translated vs. expected key counts and completion percentage
Outdated key counts
Translated vs. expected file counts
Warnings for language codes the API doesn’t recognize

Integration Examples

CI/CD Pipeline

name: Update Translations
on:
  push:
    paths: ['src/locales/en/**']

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - name: Install Algebras CLI
        run: pip install git+https://github.com/algebras-ai/algebras-cli.git
      - name: Check Translations
        run: algebras ci --only-missing
        env:
          ALGEBRAS_API_KEY: ${{ secrets.ALGEBRAS_API_KEY }}

algebras ci already exits with a non-zero status on missing/outdated translations, which fails the job — no extra flag needed.

Pre-commit Hook

#!/bin/bash
# Check if English locale files changed
if git diff --cached --name-only | grep -q "src/locales/en/"; then
    echo "English locale files changed, updating translations..."
    algebras update --only-missing
    git add src/locales/
fi

Troubleshooting Advanced Features

UI-Safe Issues

Problem: Translations still too long Solution: Check glossary terms and adjust prompt specificity

Batch Processing Errors

Problem: Rate limit errors Solution: Reduce --max-parallel-batches or increase --batch-size

Git Integration Issues

Problem: Unnecessary translations Solution: Ensure source files are properly tracked in Git

Performance Issues

Problem: Slow translations Solutions:

Increase --batch-size
Increase --max-parallel-batches
Use --only-missing for updates

Next Steps

Troubleshooting - Common issues and solutions
Commands Reference - Complete command reference
Configuration - Detailed configuration options