traductor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cf478916abe688a2b19d099ab687a4a2a212183c45075640c75929722c9d528
+  data.tar.gz: 45508818d262d06d5bc04db0c54a45b8137a88eb9a539a1426a5c7dd85c83f53
+SHA512:
+  metadata.gz: 532e43c9a7d48e843b9489287c93965c57ffb37778aae126ddbc29a16c0b2919de9452749a73ac91fa3b78f9eb11589a62030897902b1e8ed28e8706a38e2166
+  data.tar.gz: 448cdb7685fe96afff23c2d5bebd62500fedb54718b6ba8778b58abec61a1e9abb41267c557d536744adab1f3321823f12efafba3812ecc0474ebe110e0538cf

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alvaro Delgado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,252 @@
+<p align="center">
+  <img src="assets/traductor-logo.svg" alt="Traductor" width="400">
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/traductor"><img src="https://img.shields.io/gem/v/traductor.svg?color=e74c3c" alt="Gem Version"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <a href="https://ruby-doc.org/core-3.1.0/"><img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg" alt="Ruby >= 3.1"></a>
+</p>
+
+---
+
+**Traductor** is an AI-powered locale file translator for Ruby applications. It uses [RubyLLM](https://github.com/crmne/ruby_llm) 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:
+
+```ruby
+gem "traductor"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install traductor
+```
+
+## Quick Start
+
+### 1. Initialize configuration
+
+```sh
+traductor init
+```
+
+This creates a `.traductor.yml` in your project root:
+
+```yaml
+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:
+
+```sh
+# 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
+
+```sh
+# 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
+
+```sh
+# 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
+
+```ruby
+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:
+
+```yaml
+"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)
+  │
+  ├─ Parse & flatten nested keys to dot-notation
+  ├─ Diff against existing target (incremental mode)
+  ├─ Protect interpolation variables (%{name} → __TVAR0__)
+  ├─ Batch related keys by namespace
+  ├─ Build prompt with glossary + translation rules
+  ├─ Send to LLM via RubyLLM
+  ├─ Parse JSON response
+  ├─ Restore interpolation variables (__TVAR0__ → %{name})
+  ├─ Merge with existing translations
+  └─ Write target locale file (es.yml / es.json)
+```
+
+## Configuration
+
+Full `.traductor.yml` reference:
+
+```yaml
+# 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
+
+```sh
+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](https://github.com/AAlvAAro/traductor).
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/assets/traductor-logo.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 120" fill="none">
+  <!-- Background -->
+  <rect width="400" height="120" rx="12" fill="#1a1a2e"/>
+
+  <!-- Globe icon -->
+  <circle cx="60" cy="60" r="32" stroke="#e74c3c" stroke-width="2.5" fill="none" opacity="0.9"/>
+  <ellipse cx="60" cy="60" rx="14" ry="32" stroke="#e74c3c" stroke-width="2" fill="none" opacity="0.7"/>
+  <line x1="28" y1="60" x2="92" y2="60" stroke="#e74c3c" stroke-width="1.5" opacity="0.5"/>
+  <line x1="28" y1="44" x2="92" y2="44" stroke="#e74c3c" stroke-width="1" opacity="0.3"/>
+  <line x1="28" y1="76" x2="92" y2="76" stroke="#e74c3c" stroke-width="1" opacity="0.3"/>
+
+  <!-- Translation arrows -->
+  <path d="M 80 38 L 95 38" stroke="#3498db" stroke-width="2" stroke-linecap="round"/>
+  <path d="M 91 34 L 95 38 L 91 42" stroke="#3498db" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+
+  <path d="M 80 82 L 95 82" stroke="#2ecc71" stroke-width="2" stroke-linecap="round"/>
+  <path d="M 91 78 L 95 82 L 91 86" stroke="#2ecc71" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+
+  <!-- Small speech bubbles -->
+  <rect x="97" y="30" width="16" height="12" rx="3" fill="#3498db" opacity="0.8"/>
+  <text x="101" y="40" font-family="monospace" font-size="7" fill="white" font-weight="bold">EN</text>
+
+  <rect x="97" y="74" width="16" height="12" rx="3" fill="#2ecc71" opacity="0.8"/>
+  <text x="101" y="84" font-family="monospace" font-size="7" fill="white" font-weight="bold">ES</text>
+
+  <!-- Gem name -->
+  <text x="130" y="55" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="32" fill="white" font-weight="700" letter-spacing="-0.5">traductor</text>
+
+  <!-- Tagline -->
+  <text x="130" y="78" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif" font-size="13" fill="#888" font-weight="400">AI-powered locale translator</text>
+
+  <!-- Ruby gem badge -->
+  <rect x="130" y="86" width="46" height="16" rx="4" fill="#e74c3c" opacity="0.15"/>
+  <text x="136" y="97" font-family="monospace" font-size="9" fill="#e74c3c" opacity="0.9">ruby</text>
+  <rect x="182" y="86" width="86" height="16" rx="4" fill="#3498db" opacity="0.15"/>
+  <text x="188" y="97" font-family="monospace" font-size="9" fill="#3498db" opacity="0.9">model-agnostic</text>
+</svg>

data/exe/traductor

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "traductor"
+require "traductor/cli"
+
+Traductor::CLI.start(ARGV)

data/lib/traductor/batch_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Traductor
+  class BatchBuilder
+    def initialize(flat_keys, batch_size:)
+      @flat_keys = flat_keys
+      @batch_size = batch_size
+    end
+
+    # Groups keys by their top-level namespace, then splits into
+    # batches of at most batch_size entries.
+    def build
+      grouped = group_by_namespace
+      batches = []
+
+      grouped.each_value do |keys_hash|
+        keys_hash.each_slice(@batch_size) do |slice|
+          batches << slice.to_h
+        end
+      end
+
+      batches.reject(&:empty?)
+    end
+
+    private
+
+    def group_by_namespace
+      @flat_keys.group_by { |key, _value| key.split(".").first }
+    end
+  end
+end

data/lib/traductor/cli.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Traductor
+  class CLI < Thor
+    desc "init", "Create a .traductor.yml configuration file"
+    option :source, type: :string, default: "en", desc: "Source locale code"
+    def init
+      if File.exist?(".traductor.yml")
+        say ".traductor.yml already exists", :yellow
+        return
+      end
+
+      content = <<~YAML
+        # Traductor configuration
+        source_locale: #{options[:source]}
+        target_locales:
+          - es
+          - fr
+
+        # Source file paths (glob patterns supported)
+        source_paths:
+          - config/locales/#{options[:source]}.yml
+
+        # Output directory (defaults to same directory as source file)
+        # output_dir: config/locales
+
+        # LLM settings (any model supported by RubyLLM)
+        # model: gpt-4.1-mini
+        # temperature: 0.3
+
+        # Translation settings
+        # batch_size: 30
+        # glossary_path: .traductor-glossary.yml
+      YAML
+
+      File.write(".traductor.yml", content)
+      say "Created .traductor.yml", :green
+      say "Edit the file to configure your locales and source paths."
+    end
+
+    desc "translate", "Translate source locale file(s) to target languages"
+    option :source, type: :string, desc: "Source file path (overrides config)"
+    option :targets, type: :array, desc: "Target locale codes (overrides config)"
+    option :model, type: :string, desc: "LLM model to use (overrides config)"
+    option :full, type: :boolean, default: false, desc: "Force full re-translation"
+    option :config, type: :string, default: ".traductor.yml", desc: "Config file path"
+    option :output, type: :string, desc: "Output directory (overrides config)"
+    option :dry_run, type: :boolean, default: false, desc: "Show what would be translated"
+    def translate
+      load_config(options[:config])
+      apply_overrides
+
+      source_paths = resolve_source_paths
+      target_locales = resolve_target_locales
+
+      if source_paths.empty?
+        say "No source files found. Run 'traductor init' or specify --source.", :red
+        return
+      end
+
+      if target_locales.empty?
+        say "No target locales specified. Edit .traductor.yml or use --targets.", :red
+        return
+      end
+
+      source_paths.each do |source_path|
+        say "Source: #{source_path}", :blue
+
+        translator = Translator.new(
+          source_path: source_path,
+          target_locales: target_locales,
+          output_dir: options[:output] || Traductor.configuration.output_dir,
+          incremental: !options[:full]
+        )
+
+        if options[:dry_run]
+          summary = translator.dry_run
+          summary.each do |locale, info|
+            say "  #{locale}: #{info[:keys_to_translate]} keys to translate", :cyan
+            info[:keys].first(10).each { |key| say "    - #{key}" }
+            say "    ... and #{info[:keys].size - 10} more" if info[:keys].size > 10
+          end
+        else
+          result = translator.call
+
+          result.results.each do |locale, path|
+            say "  #{locale}: #{path}", :green
+          end
+
+          result.errors.each do |error|
+            say "  #{error[:locale]}: ERROR - #{error[:error]}", :red
+          end
+        end
+      end
+    end
+
+    desc "diff", "Show translation differences between source and target"
+    option :source, type: :string, desc: "Source file path"
+    option :target, type: :string, desc: "Target file path or locale code"
+    option :config, type: :string, default: ".traductor.yml", desc: "Config file path"
+    def diff
+      load_config(options[:config])
+
+      source_path = options[:source] || Traductor.configuration.source_paths&.first
+      unless source_path && File.exist?(source_path)
+        say "Source file not found: #{source_path}", :red
+        return
+      end
+
+      source_file = LocaleFile.new(source_path)
+      source_flat = KeyFlattener.flatten(source_file.content)
+
+      target_path = resolve_target_path(options[:target], source_path)
+      unless target_path && File.exist?(target_path)
+        say "Target file not found: #{target_path}", :red
+        return
+      end
+
+      target_file = LocaleFile.new(target_path)
+      target_flat = KeyFlattener.flatten(target_file.content)
+
+      diff = Diff.new(source_flat: source_flat, target_flat: target_flat)
+
+      say "Diff: #{source_path} -> #{target_path}", :blue
+      say ""
+
+      if diff.added.any?
+        say "Added (#{diff.added.size} keys need translation):", :green
+        diff.added.each { |key, value| say "  + #{key}: #{value}" }
+        say ""
+      end
+
+      if diff.removed.any?
+        say "Removed (#{diff.removed.size} keys in target but not in source):", :red
+        diff.removed.each { |key, _| say "  - #{key}" }
+        say ""
+      end
+
+      say "Unchanged: #{diff.unchanged.size} keys", :cyan
+      say diff.summary.inspect
+    end
+
+    desc "version", "Show Traductor version"
+    def version
+      say "traductor #{Traductor::VERSION}"
+    end
+
+    private
+
+    def load_config(path)
+      Traductor.configuration.load_from_file(path)
+    end
+
+    def apply_overrides
+      config = Traductor.configuration
+      config.model = options[:model] if options[:model]
+    end
+
+    def resolve_source_paths
+      if options[:source]
+        [options[:source]]
+      else
+        paths = Array(Traductor.configuration.source_paths)
+        paths.flat_map { |pattern| Dir.glob(pattern) }
+      end
+    end
+
+    def resolve_target_locales
+      options[:targets] || Array(Traductor.configuration.target_locales).map(&:to_s)
+    end
+
+    def resolve_target_path(target_option, source_path)
+      return target_option if target_option&.include?(".")
+
+      locale = target_option || Traductor.configuration.target_locales&.first
+      return nil unless locale
+
+      ext = File.extname(source_path)
+      dir = File.dirname(source_path)
+      File.join(dir, "#{locale}#{ext}")
+    end
+  end
+end

data/lib/traductor/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Traductor
+  class Configuration
+    attr_accessor :source_locale, :target_locales, :source_paths,
+                  :output_dir, :model, :provider, :temperature,
+                  :glossary_path, :batch_size
+
+    def initialize
+      @source_locale = "en"
+      @target_locales = []
+      @source_paths = []
+      @output_dir = nil
+      @model = nil
+      @provider = nil
+      @temperature = 0.3
+      @glossary_path = nil
+      @batch_size = 30
+    end
+
+    def load_from_file(path = ".traductor.yml")
+      return unless File.exist?(path)
+
+      yaml = YAML.safe_load_file(path, permitted_classes: [Symbol])
+      return unless yaml.is_a?(Hash)
+
+      apply_hash(yaml)
+    end
+
+    private
+
+    def apply_hash(hash)
+      hash.each do |key, value|
+        setter = :"#{key}="
+        public_send(setter, value) if respond_to?(setter)
+      end
+    end
+  end
+end

data/lib/traductor/diff.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Traductor
+  class Diff
+    attr_reader :added, :removed, :unchanged
+
+    def initialize(source_flat:, target_flat:)
+      @source_flat = source_flat
+      @target_flat = target_flat
+      compute
+    end
+
+    # Returns only the keys that need translation (new keys not yet in target)
+    def keys_to_translate
+      @added
+    end
+
+    def summary
+      {
+        added: @added.size,
+        removed: @removed.size,
+        unchanged: @unchanged.size
+      }
+    end
+
+    private
+
+    def compute
+      @added = {}
+      @removed = {}
+      @unchanged = {}
+
+      @source_flat.each do |key, value|
+        if @target_flat.key?(key)
+          @unchanged[key] = @target_flat[key]
+        else
+          @added[key] = value
+        end
+      end
+
+      @removed = @target_flat.reject { |key, _| @source_flat.key?(key) }
+    end
+  end
+end

data/lib/traductor/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Traductor
+  class Error < StandardError; end
+  class UnsupportedFormatError < Error; end
+  class TranslationParseError < Error; end
+  class ConfigurationError < Error; end
+end

data/lib/traductor/glossary.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Traductor
+  class Glossary
+    attr_reader :terms
+
+    def initialize(path = nil)
+      @terms = path && File.exist?(path) ? load_terms(path) : {}
+    end
+
+    # Returns terms relevant to a specific target locale
+    def for_locale(locale)
+      locale = locale.to_s
+      @terms.select { |_term, translations| translations.key?(locale) }
+    end
+
+    # Formats glossary entries for inclusion in prompts
+    def to_prompt_text(locale)
+      entries = for_locale(locale)
+      return nil if entries.empty?
+
+      entries.map { |term, translations|
+        "- \"#{term}\" -> \"#{translations[locale.to_s]}\""
+      }.join("\n")
+    end
+
+    private
+
+    def load_terms(path)
+      YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+    end
+  end
+end

data/lib/traductor/interpolation_guard.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Traductor
+  class InterpolationGuard
+    PATTERNS = [
+      /(%\{[^}]+\})/,       # Ruby/Rails: %{name}
+      /(\{\{[^}]+\}\})/,    # Handlebars/React: {{variable}}
+      /(\$\{[^}]+\})/,      # ES6 template literals: ${variable}
+    ].freeze
+
+    COMBINED_PATTERN = Regexp.union(PATTERNS)
+
+    def initialize
+      @placeholders = {}
+      @counter = 0
+    end
+
+    # Replace interpolation variables with numbered placeholders
+    def protect(text)
+      return text unless text.is_a?(String)
+
+      text.gsub(COMBINED_PATTERN) do |match|
+        placeholder = "__TVAR#{@counter}__"
+        @placeholders[placeholder] = match
+        @counter += 1
+        placeholder
+      end
+    end
+
+    # Restore original interpolation variables from placeholders
+    def restore(text)
+      return text unless text.is_a?(String)
+
+      result = text.dup
+      @placeholders.each do |placeholder, original|
+        result.gsub!(placeholder, original)
+      end
+      result
+    end
+
+    def reset!
+      @placeholders.clear
+      @counter = 0
+    end
+  end
+end

data/lib/traductor/key_flattener.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Traductor
+  class KeyFlattener
+    # Converts a nested hash to flat dot-notation key-value pairs.
+    #
+    #   {"users" => {"greeting" => "Hello %{name}"}}
+    #   => {"users.greeting" => "Hello %{name}"}
+    #
+    def self.flatten(hash, prefix = nil)
+      hash.each_with_object({}) do |(key, value), result|
+        full_key = [prefix, key].compact.join(".")
+        if value.is_a?(Hash)
+          result.merge!(flatten(value, full_key))
+        else
+          result[full_key] = value
+        end
+      end
+    end
+
+    # Converts flat dot-notation key-value pairs back to a nested hash.
+    #
+    #   {"users.greeting" => "Hola %{name}"}
+    #   => {"users" => {"greeting" => "Hola %{name}"}}
+    #
+    def self.unflatten(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        parts = key.split(".")
+        current = result
+        parts[0..-2].each do |part|
+          current[part] ||= {}
+          current = current[part]
+        end
+        current[parts.last] = value
+      end
+    end
+  end
+end

data/lib/traductor/locale_file.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module Traductor
+  class LocaleFile
+    attr_reader :path, :format, :data, :locale
+
+    def initialize(path)
+      @path = path
+      @format = detect_format(path)
+      @data = parse
+      @locale = extract_locale
+    end
+
+    # Returns the content hash without the top-level locale key.
+    # For YAML: {"en" => {"hello" => "Hello"}} -> {"hello" => "Hello"}
+    # For JSON: returns as-is if no single top-level locale key
+    def content
+      if data.is_a?(Hash) && data.keys.length == 1
+        data.values.first
+      else
+        data
+      end
+    end
+
+    def write(data, output_path)
+      dir = File.dirname(output_path)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+      case detect_format(output_path)
+      when :yaml
+        File.write(output_path, data.to_yaml)
+      when :json
+        File.write(output_path, JSON.pretty_generate(data) + "\n")
+      end
+    end
+
+    private
+
+    def parse
+      case format
+      when :yaml then YAML.safe_load_file(path, permitted_classes: [Symbol])
+      when :json then JSON.parse(File.read(path))
+      end
+    end
+
+    def detect_format(file_path)
+      case File.extname(file_path).downcase
+      when ".yml", ".yaml" then :yaml
+      when ".json" then :json
+      else raise UnsupportedFormatError, "Unsupported file format: #{File.extname(file_path)}"
+      end
+    end
+
+    def extract_locale
+      if data.is_a?(Hash) && data.keys.length == 1
+        data.keys.first
+      else
+        File.basename(path, File.extname(path))
+      end
+    end
+  end
+end

data/lib/traductor/prompt_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Traductor
+  class PromptBuilder
+    def initialize(source_locale:, target_locale:, glossary: nil)
+      @source_locale = source_locale
+      @target_locale = target_locale
+      @glossary = glossary
+    end
+
+    def system_prompt
+      parts = []
+      parts << <<~PROMPT.strip
+        You are a professional translator specializing in software localization.
+        You translate from #{locale_name(@source_locale)} to #{locale_name(@target_locale)}.
+
+        Rules:
+        1. Translate ONLY the values, never the keys.
+        2. Preserve all placeholders exactly as they appear (e.g., __TVAR0__, __TVAR1__). Do not translate, modify, or reorder placeholders.
+        3. Maintain the same tone and formality level as the source text.
+        4. For technical terms (e.g., API, URL, HTML), keep them untranslated unless there is a well-established localized term.
+        5. Handle pluralization naturally for the target language.
+        6. Keep translations concise — UI strings should remain similar in length.
+        7. Respond ONLY with valid JSON. No explanations, no markdown fences, no extra text.
+      PROMPT
+
+      if @glossary
+        glossary_text = @glossary.to_prompt_text(@target_locale)
+        if glossary_text
+          parts << <<~GLOSSARY.strip
+
+            Glossary — always use these exact translations:
+            #{glossary_text}
+          GLOSSARY
+        end
+      end
+
+      parts.join("\n\n")
+    end
+
+    def user_prompt(batch)
+      <<~PROMPT.strip
+        Translate the following JSON object's values from #{locale_name(@source_locale)} to #{locale_name(@target_locale)}.
+        Return a JSON object with the same keys and translated values.
+
+        #{JSON.generate(batch)}
+      PROMPT
+    end
+
+    private
+
+    def locale_name(code)
+      LOCALE_NAMES.fetch(code.to_s, code.to_s)
+    end
+
+    LOCALE_NAMES = {
+      "en" => "English", "es" => "Spanish", "fr" => "French",
+      "de" => "German", "pt" => "Portuguese", "it" => "Italian",
+      "ja" => "Japanese", "ko" => "Korean", "zh" => "Chinese",
+      "ar" => "Arabic", "ru" => "Russian", "nl" => "Dutch",
+      "sv" => "Swedish", "pl" => "Polish", "tr" => "Turkish",
+      "th" => "Thai", "vi" => "Vietnamese", "hi" => "Hindi",
+      "uk" => "Ukrainian", "cs" => "Czech", "da" => "Danish",
+      "fi" => "Finnish", "el" => "Greek", "he" => "Hebrew",
+      "hu" => "Hungarian", "id" => "Indonesian", "ms" => "Malay",
+      "no" => "Norwegian", "ro" => "Romanian", "sk" => "Slovak",
+      "bg" => "Bulgarian", "ca" => "Catalan", "hr" => "Croatian",
+      "et" => "Estonian", "lv" => "Latvian", "lt" => "Lithuanian",
+      "sl" => "Slovenian", "sr" => "Serbian",
+      "pt-BR" => "Brazilian Portuguese",
+      "zh-TW" => "Traditional Chinese",
+      "zh-CN" => "Simplified Chinese"
+    }.freeze
+  end
+end

data/lib/traductor/result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Traductor
+  class Result
+    attr_reader :results, :errors
+
+    def initialize(results: {}, errors: [])
+      @results = results
+      @errors = errors
+    end
+
+    def success?
+      @errors.empty?
+    end
+
+    def locales
+      @results.keys
+    end
+
+    def path_for(locale)
+      @results[locale.to_s]
+    end
+  end
+end

data/lib/traductor/translator.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "fileutils"
+
+module Traductor
+  class Translator
+    def initialize(source_path:, target_locales:, output_dir: nil, incremental: true)
+      @source_file = LocaleFile.new(source_path)
+      @target_locales = Array(target_locales).map(&:to_s)
+      @output_dir = output_dir || File.dirname(source_path)
+      @incremental = incremental
+      @config = Traductor.configuration
+      @glossary = Glossary.new(@config.glossary_path)
+    end
+
+    def call
+      source_flat = KeyFlattener.flatten(@source_file.content)
+      results = {}
+      errors = []
+
+      @target_locales.each do |target_locale|
+        path = translate_locale(source_flat, target_locale)
+        results[target_locale] = path
+      rescue StandardError => e
+        errors << { locale: target_locale, error: e.message }
+      end
+
+      Result.new(results: results, errors: errors)
+    end
+
+    # Returns keys that would be translated without calling the LLM
+    def dry_run
+      source_flat = KeyFlattener.flatten(@source_file.content)
+      summary = {}
+
+      @target_locales.each do |target_locale|
+        keys = if @incremental
+                 determine_keys_to_translate(source_flat, target_locale)
+               else
+                 source_flat
+               end
+        summary[target_locale] = {
+          keys_to_translate: keys.size,
+          keys: keys.keys
+        }
+      end
+
+      summary
+    end
+
+    private
+
+    def translate_locale(source_flat, target_locale)
+      keys_to_translate = if @incremental
+                            determine_keys_to_translate(source_flat, target_locale)
+                          else
+                            source_flat
+                          end
+
+      if keys_to_translate.empty?
+        return output_path_for(target_locale)
+      end
+
+      guard = InterpolationGuard.new
+      protected_keys = keys_to_translate.each_with_object({}) do |(key, value), hash|
+        hash[key] = value.is_a?(String) ? guard.protect(value) : value
+      end
+
+      batches = BatchBuilder.new(protected_keys, batch_size: @config.batch_size).build
+      prompt_builder = PromptBuilder.new(
+        source_locale: @source_file.locale,
+        target_locale: target_locale,
+        glossary: @glossary
+      )
+
+      chat = build_chat
+      chat.with_instructions(prompt_builder.system_prompt)
+
+      translated_flat = {}
+
+      batches.each do |batch|
+        response = chat.ask(prompt_builder.user_prompt(batch))
+        parsed = parse_response(response.content)
+        restored = parsed.each_with_object({}) do |(key, value), hash|
+          hash[key] = value.is_a?(String) ? guard.restore(value) : value
+        end
+        translated_flat.merge!(restored)
+        guard.reset!
+      end
+
+      write_output(target_locale, translated_flat)
+    end
+
+    def determine_keys_to_translate(source_flat, target_locale)
+      target_path = output_path_for(target_locale)
+      return source_flat unless File.exist?(target_path)
+
+      target_file = LocaleFile.new(target_path)
+      target_flat = KeyFlattener.flatten(target_file.content)
+
+      diff = Diff.new(source_flat: source_flat, target_flat: target_flat)
+      diff.keys_to_translate
+    end
+
+    def write_output(target_locale, translated_flat)
+      existing_flat = load_existing_translations(target_locale)
+      merged = existing_flat.merge(translated_flat)
+
+      nested = KeyFlattener.unflatten(merged)
+      output_data = { target_locale => nested }
+
+      path = output_path_for(target_locale)
+      @source_file.write(output_data, path)
+      path
+    end
+
+    def load_existing_translations(target_locale)
+      path = output_path_for(target_locale)
+      return {} unless File.exist?(path)
+
+      file = LocaleFile.new(path)
+      KeyFlattener.flatten(file.content)
+    end
+
+    def output_path_for(target_locale)
+      ext = File.extname(@source_file.path)
+      File.join(@output_dir, "#{target_locale}#{ext}")
+    end
+
+    def build_chat
+      args = {}
+      args[:model] = @config.model if @config.model
+      chat = RubyLLM.chat(**args)
+      chat.with_temperature(@config.temperature)
+      chat
+    end
+
+    def parse_response(content)
+      cleaned = content.gsub(/\A```(?:json)?\n?/, "").gsub(/\n?```\z/, "").strip
+      JSON.parse(cleaned)
+    rescue JSON::ParserError => e
+      raise TranslationParseError, "Failed to parse LLM response as JSON: #{e.message}\nResponse: #{content}"
+    end
+  end
+end

data/lib/traductor/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Traductor
+  VERSION = "0.1.0"
+end

data/lib/traductor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "traductor/version"
+require_relative "traductor/errors"
+require_relative "traductor/configuration"
+require_relative "traductor/key_flattener"
+require_relative "traductor/locale_file"
+require_relative "traductor/interpolation_guard"
+require_relative "traductor/diff"
+require_relative "traductor/glossary"
+require_relative "traductor/batch_builder"
+require_relative "traductor/prompt_builder"
+require_relative "traductor/translator"
+require_relative "traductor/result"
+
+module Traductor
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Primary API: translate a source file to target locales
+    #
+    #   Traductor.translate("config/locales/en.yml", target_locales: ["es", "fr"])
+    #
+    def translate(source_path, target_locales:, output_dir: nil, incremental: true)
+      Translator.new(
+        source_path: source_path,
+        target_locales: target_locales,
+        output_dir: output_dir,
+        incremental: incremental
+      ).call
+    end
+  end
+end

data/sig/traductor.rbs

@@ -0,0 +1,4 @@
+module Traductor
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: traductor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alvaro Delgado
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Traductor uses RubyLLM to translate YAML and JSON locale files across
+  languages. Supports incremental translation, glossaries, interpolation variable
+  protection, and works with any framework (Rails, React, Next.js).
+email:
+- hola@alvarodelgado.dev
+executables:
+- traductor
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- assets/traductor-logo.svg
+- exe/traductor
+- lib/traductor.rb
+- lib/traductor/batch_builder.rb
+- lib/traductor/cli.rb
+- lib/traductor/configuration.rb
+- lib/traductor/diff.rb
+- lib/traductor/errors.rb
+- lib/traductor/glossary.rb
+- lib/traductor/interpolation_guard.rb
+- lib/traductor/key_flattener.rb
+- lib/traductor/locale_file.rb
+- lib/traductor/prompt_builder.rb
+- lib/traductor/result.rb
+- lib/traductor/translator.rb
+- lib/traductor/version.rb
+- sig/traductor.rbs
+homepage: https://github.com/AAlvAAro/traductor
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/AAlvAAro/traductor
+  source_code_uri: https://github.com/AAlvAAro/traductor
+  changelog_uri: https://github.com/AAlvAAro/traductor/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: AI-powered locale file translator for Ruby applications
+test_files: []