Skip to content
Algebras

Configuration

The Algebras CLI uses a .algebras.config file to manage your project settings. This file defines which languages to translate, where your source files are located, and how translations should be generated.

Initial Setup

Section titled “Initial Setup”

Create Configuration File

Section titled “Create Configuration File”

Run this command in your project root:

Terminal window
algebras init

This creates a .algebras.config file with default settings.

Force Regenerate Configuration

Section titled “Force Regenerate Configuration”

To regenerate your configuration with the latest format:

Terminal window
algebras init --force

Configuration File Structure

Section titled “Configuration File Structure”

The .algebras.config file uses YAML format and contains several sections:

languages:
  - en
  - es
  - fr
  - de


source_files:
  "src/locales/en/common.json":
    destination_path: "src/locales/%algebras_locale_code%/common.json"
  "public/locales/en/translation.json":
    destination_path: "public/locales/%algebras_locale_code%/translation.json"


api:
  provider: algebras-ai

Configuration Sections

Section titled “Configuration Sections”

Languages

Section titled “Languages”

Define which languages your application should support:

languages:
  - en      # English (source)
  - es      # Spanish
  - fr      # French
  - de      # German
  - pt_BR   # Brazilian Portuguese
  - ja      # Japanese

Source Files

Section titled “Source Files”

Map your source files to destination patterns using the %algebras_locale_code% placeholder:

source_files:
  "src/locales/en/common.json":
    destination_path: "src/locales/%algebras_locale_code%/common.json"
  "public/locales/en/translation.json":
    destination_path: "public/locales/%algebras_locale_code%/translation.json"
  "locale/en/LC_MESSAGES/django.po":
    destination_path: "locale/%algebras_locale_code%/LC_MESSAGES/django.po"

The %algebras_locale_code% placeholder is replaced with the actual locale code (e.g., en, fr, es, pt_BR).

API Configuration

Section titled “API Configuration”

Configure your translation provider:

api:
  provider: algebras-ai  # Default and currently only supported provider

Framework-Specific Examples

Section titled “Framework-Specific Examples”

Next.js/React (next-i18next)

Section titled “Next.js/React (next-i18next)”
languages:
  - en
  - es
  - fr


source_files:
  "public/locales/en/common.json":
    destination_path: "public/locales/%algebras_locale_code%/common.json"
  "public/locales/en/translation.json":
    destination_path: "public/locales/%algebras_locale_code%/translation.json"

Django (gettext)

Section titled “Django (gettext)”
languages:
  - en
  - es
  - fr


source_files:
  "locale/en/LC_MESSAGES/django.po":
    destination_path: "locale/%algebras_locale_code%/LC_MESSAGES/django.po"

Android (values directories)

Section titled “Android (values directories)”
languages:
  - en
  - es
  - fr


source_files:
  "app/src/main/res/values/strings.xml":
    destination_path: "app/src/main/res/values-%algebras_locale_code%/strings.xml"

iOS (strings files)

Section titled “iOS (strings files)”
languages:
  - en
  - es
  - fr


source_files:
  "ios/App/en.lproj/Localizable.strings":
    destination_path: "ios/App/%algebras_locale_code%.lproj/Localizable.strings"

HTML Files

Section titled “HTML Files”
languages:
  - en
  - es
  - fr


source_files:
  "html_files/index.html":
    destination_path: "html_files/index.%algebras_locale_code%.html"

Environment Variables

Section titled “Environment Variables”

Configure the CLI using environment variables:

Required Variables

Section titled “Required Variables”
Terminal window
export ALGEBRAS_API_KEY=your_api_key_here

Optional Variables

Section titled “Optional Variables”
Terminal window
export ALGEBRAS_BASE_URL=https://platform.algebras.ai
export ALGEBRAS_BATCH_SIZE=20
export ALGEBRAS_MAX_PARALLEL_BATCHES=5

Advanced Configuration

Section titled “Advanced Configuration”

Batch Processing Settings

Section titled “Batch Processing Settings”
batch_size: 10
max_parallel_batches: 3

batch_size and max_parallel_batches are top-level config keys (not nested under api), matching what algebras configure --batch-size/--max-parallel-batches write.

String Normalization

Section titled “String Normalization”

Control how strings are processed before translation:

api:
  provider: algebras-ai
  normalize_strings: true  # Remove escaped characters like \'

Configuration Commands

Section titled “Configuration Commands”

Add a Language

Section titled “Add a Language”
Terminal window
algebras add es

add takes one language per invocation. There is no algebras remove command — remove a language by deleting its entry from languages in .algebras.config.

Configure Settings

Section titled “Configure Settings”
Terminal window
algebras configure --batch-size 10 --max-parallel-batches 3

Check Configuration

Section titled “Check Configuration”
Terminal window
algebras configure
algebras status

Migration from path_rules

Section titled “Migration from path_rules”

If you’re upgrading from the previous path_rules system:

Old Format (Deprecated)

Section titled “Old Format (Deprecated)”
path_rules:
  - "public/locales/**/*.json"
  - "!**/node_modules/**"

New Format

Section titled “New Format”
source_files:
  "public/locales/en/common.json":
    destination_path: "public/locales/%algebras_locale_code%/common.json"
  "public/locales/en/translation.json":
    destination_path: "public/locales/%algebras_locale_code%/translation.json"

Migration Steps

Section titled “Migration Steps”
  1. Run algebras init --force to regenerate configuration
  2. Review and adjust the generated source_files mappings
  3. Remove any path_rules entries from your configuration

Troubleshooting Configuration

Section titled “Troubleshooting Configuration”

“No Algebras configuration found”

Section titled ““No Algebras configuration found””

Solution: Run algebras init in your project directory.

“Language ‘xx’ is not configured”

Section titled ““Language ‘xx’ is not configured””

Solution: Add the language: algebras add xx

“No source files found”

Section titled ““No source files found””

Solutions:

  1. Configure source files in .algebras.config
  2. Run algebras init --force to regenerate configuration
  3. Check file paths are correct and files exist

Configuration Validation Errors

Section titled “Configuration Validation Errors”

Solutions:

  1. Check YAML syntax
  2. Verify file paths exist
  3. Ensure language codes are valid
  4. Run algebras status to validate configuration

Next Steps

Section titled “Next Steps”