RubyDoc.info: File: README – Documentation for traductor (0.1.0)

Traductor is an AI-powered locale file translator for Ruby applications. It uses RubyLLM under the hood, so you can translate with any LLM provider — OpenAI, Anthropic, AWS Bedrock, Google Gemini, and more.

Works with any framework: Rails (YAML), React/Next.js (JSON), or anything that uses standard locale files.

Features

Model-agnostic — Use GPT-4, Claude, Gemini, Llama, or any model supported by RubyLLM
Incremental translation — Only translates new and missing keys, saving time and cost
Interpolation protection — Safely preserves %{name}, {{variable}}, and ${value} placeholders
Glossary support — Define project-specific terminology for consistent translations
YAML + JSON — Supports Rails i18n YAML and JSON locale files out of the box
CLI + Ruby API — Use from the command line or programmatically in your code
Smart batching — Groups related keys together for contextually consistent translations

Installation

Add to your Gemfile:

gem "traductor"

Then run:

bundle install

Or install directly:

gem install traductor

Quick Start

1. Initialize configuration

traductor init

This creates a .traductor.yml in your project root:

source_locale: en
target_locales:
  - es
  - fr

source_paths:
  - config/locales/en.yml

# model: gpt-4.1-mini
# glossary_path: .traductor-glossary.yml

2. Configure your LLM provider

Traductor uses RubyLLM, so configure your provider's API key:

# Pick one (or more):
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."
export AWS_ACCESS_KEY_ID="..." && export AWS_SECRET_ACCESS_KEY="..."

3. Translate

# Preview what will be translated
traductor translate --dry-run

# Translate to all configured locales
traductor translate

# Translate to specific locales
traductor translate --targets es fr de ja

# Translate a specific file
traductor translate --source config/locales/en.yml --targets es

# Use a specific model
traductor translate --model claude-sonnet-4-5

# Force full re-translation (ignore existing translations)
traductor translate --full

4. Check differences

# See what keys need translation
traductor diff --source config/locales/en.yml --target es

CLI Reference

Command	Description
`traductor init`	Generate `.traductor.yml` configuration
`traductor translate`	Translate locale files
`traductor diff`	Show translation differences
`traductor version`	Show version

`traductor translate` options

Option	Description
`--source PATH`	Source file path (overrides config)
`--targets es fr de`	Target locale codes (overrides config)
`--model MODEL`	LLM model to use (overrides config)
`--output DIR`	Output directory (overrides config)
`--full`	Force full re-translation
`--dry-run`	Preview without calling the LLM
`--config PATH`	Config file path (default: `.traductor.yml`)

Ruby API

require "traductor"

# Configure
Traductor.configure do |config|
  config.source_locale = "en"
  config.model = "gpt-4.1-mini"
  config.temperature = 0.3
  config.batch_size = 30
  config.glossary_path = ".traductor-glossary.yml"
end

# Translate
result = Traductor.translate(
  "config/locales/en.yml",
  target_locales: ["es", "fr", "de"]
)

result.success?            # => true
result.locales             # => ["es", "fr", "de"]
result.path_for("es")      # => "config/locales/es.yml"

Glossary

Create a .traductor-glossary.yml to enforce consistent terminology:

"Sign up":
  es: "Registrarse"
  fr: "S'inscrire"
  de: "Registrieren"

"Dashboard":
  es: "Panel de control"
  fr: "Tableau de bord"
  de: "Dashboard"

Glossary terms are injected into the LLM prompt so translations always use your preferred terminology.

How It Works

Source locale file (en.yml / en.json)

Configuration

Full .traductor.yml reference:

# Source locale code
source_locale: en

# Target locales to translate into
target_locales:
  - es
  - fr
  - de
  - ja
  - pt-BR

# Source file paths (supports glob patterns)
source_paths:
  - config/locales/en.yml
  - config/locales/models/en.yml

# Output directory (defaults to same directory as source)
# output_dir: config/locales

# LLM model (any model supported by RubyLLM)
# model: gpt-4.1-mini

# Temperature (lower = more consistent, higher = more creative)
# temperature: 0.3

# Max keys per LLM request
# batch_size: 30

# Path to glossary file
# glossary_path: .traductor-glossary.yml

Supported Interpolation Formats

Format	Example	Framework
Ruby/Rails	`%{name}`	Rails i18n
Handlebars	`{{variable}}`	React, Ember
Template literals	`${value}`	JavaScript/ES6

Development

git clone https://github.com/AAlvAAro/traductor.git
cd traductor
bin/setup
bundle exec rspec

Contributing

Bug reports and pull requests are welcome on GitHub.

License

Released under the MIT License.