purizumu 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41586286c24fbf46df721821901d6a0ef19c30cc9b28f4e186202140dd84f8da
+  data.tar.gz: 9c1e474e116fa9f63c817f64f4e00727ee59e69d4c70577292e8a0446f194934
+SHA512:
+  metadata.gz: 92e7c2d4c42e313b0381ab3f6e327f897dfac150d41644d1e60ffc2d7b5a99948dd5c5679d61b0a03a4d4b79d2e8eb3490104af6a4930ab58e8a700d99699695
+  data.tar.gz: b7d7b134a4c85de69272411df15a21674188a9cedb3d811b9b58923e37d91774d0e7f27c0e97ff95a0c281a183e134631f380a44807381d0846ed165263f1e3c

data/README.md

@@ -0,0 +1,158 @@
+# Purizumu
+
+Purizumu auto-translates Rails model attributes and stores the translated content in your database. Translations are generated lazily the first time an attribute is read for a locale that does not already exist in the translation table.
+
+For example, if `Gem#human_name` is marked as translatable and a request reads that attribute while `I18n.locale` is `:jp`, Purizumu checks its translation table first. If no Japanese translation exists yet, it asks the configured translation engine to generate one, stores the result, and returns it.
+
+## Installation
+
+```bash
+gem install purizumu
+```
+
+Or add it to your Rails application's Gemfile:
+
+```ruby
+gem "purizumu"
+```
+
+Then install dependencies:
+
+```bash
+bundle install
+```
+
+Generate the migration and migrate:
+
+```bash
+rails generate purizumu:install
+rails db:migrate
+```
+
+## Configuration
+
+Create an initializer such as `config/initializers/purizumu.rb`:
+
+```ruby
+Purizumu.configure do |config|
+  config.engine = :xai
+  config.key = ENV["XAI_TRANSLATE_KEY"]
+  config.model = "grok-4.20-reasoning"
+end
+```
+
+Available configuration options:
+
+- `config.engine`: translation engine symbol. Purizumu currently ships with `:xai`.
+- `config.key`: API key for the configured engine.
+- `config.model`: LLM model name.
+- `config.base_url`: API base URL. Defaults to `https://api.x.ai/v1`.
+- `config.source_locale`: source locale used for untranslated records. Defaults to `I18n.default_locale`.
+- `config.transport`: optional callable used for HTTP requests. Mainly useful for testing or custom networking.
+
+## Usage
+
+Mark model attributes as translatable:
+
+```ruby
+class Gem < ApplicationRecord
+  attribute_translation :human_name
+end
+```
+
+When the attribute is read, Purizumu checks the translations table before falling back to generation:
+
+```ruby
+class GemsController < ApplicationController
+  def index
+    gem = Gem.find(48_127)
+
+    I18n.locale = :en
+    puts gem.human_name
+
+    I18n.locale = :jp
+    puts gem.human_name
+
+    I18n.locale = :ru
+    puts gem.human_name
+  end
+end
+```
+
+Example output:
+
+```text
+Prism
+プリズム
+Призма
+```
+
+## How It Works
+
+Purizumu stores translations in `purizumu_translations`. Each translation row is keyed by:
+
+- `model_class_name`
+- `record_id`
+- `attribute_name`
+- `locale`
+
+The table also stores the translated `content`.
+
+This means a single model record can have a different translation for each tracked attribute and locale.
+
+Example rows:
+
+| model_class_name | record_id | attribute_name | locale | content |
+| ---------- | --------- | -------------- | ------ | ------- |
+| Gem        | 48127     | human_name     | en     | Prism |
+| Gem        | 48127     | human_name     | es     | Prisma |
+| Gem        | 48127     | human_name     | jp     | プリズム |
+| Gem        | 48127     | human_name     | ru     | Призма |
+| Gem        | 73491     | human_name     | en     | Different Gem |
+| Gem        | 73491     | human_name     | es     | Gema Diferente |
+| Gem        | 73491     | human_name     | jp     | 異なる宝石 |
+| Gem        | 73491     | human_name     | ru     | Другой самоцвет |
+
+Purizumu intentionally uses Rails-safe key names in the translation table:
+
+- `record_id` is used instead of a plain `id` column because the table needs its own primary key.
+- `model_class_name` is used instead of `model_name` because `model_name` is already defined by Active Record internals.
+
+## xAI / Grok Engine
+
+The bundled xAI engine uses the chat completions API and enforces structured output with a function tool. It does not rely on "please return JSON" prompting alone. Purizumu sends a single required function definition and forces the model to answer through that tool call.
+
+The expected tool payload is:
+
+```json
+{
+  "translated_text": "..."
+}
+```
+
+## Generator Output
+
+`rails generate purizumu:install` creates a migration for the translation table with:
+
+- `model_name`
+- `model_class_name`
+- `record_id`
+- `attribute_name`
+- `locale`
+- `content`
+
+It also adds a unique composite index across `model_class_name`, `record_id`, `attribute_name`, and `locale`.
+
+## Development
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run Rubocop:
+
+```bash
+bundle exec rubocop
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/generators/purizumu/install/install_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Purizumu
+  module Generators
+    # Generates the migration that creates Purizumu's translation cache table.
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template(
+          'create_purizumu_translations.rb.erb',
+          'db/migrate/create_purizumu_translations.rb'
+        )
+      end
+    end
+  end
+end

data/lib/generators/purizumu/install/templates/create_purizumu_translations.rb.erb

@@ -0,0 +1,18 @@
+class CreatePurizumuTranslations < ActiveRecord::Migration[7.0]
+  def change
+    create_table :purizumu_translations do |t|
+      t.string :model_class_name, null: false
+      t.bigint :record_id, null: false
+      t.string :attribute_name, null: false
+      t.string :locale, null: false
+      t.text :content, null: false
+
+      t.timestamps
+    end
+
+    add_index :purizumu_translations,
+              %i[model_class_name record_id attribute_name locale],
+              unique: true,
+              name: "index_purizumu_translations_uniqueness"
+  end
+end

data/lib/purizumu/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Purizumu
+  # Stores runtime configuration used by translation engines.
+  class Configuration
+    attr_accessor :base_url, :engine, :key, :model, :source_locale, :transport
+
+    def initialize
+      @engine = :xai
+      @base_url = 'https://api.x.ai/v1'
+      @source_locale = nil
+      @transport = nil
+    end
+
+    def resolved_source_locale
+      (source_locale || I18n.default_locale).to_s
+    end
+  end
+end

data/lib/purizumu/engines/xai/payload_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Purizumu
+  module Engines
+    class Xai
+      # Builds the tool-enforced request payload sent to xAI.
+      class PayloadBuilder
+        TOOL_NAME = Xai::TOOL_NAME
+
+        def initialize(configuration:, request:)
+          @configuration = configuration
+          @request = request
+        end
+
+        def to_json(*_args)
+          {
+            model: configuration.model,
+            messages: messages,
+            tools: [tool_definition],
+            tool_choice: tool_choice
+          }.to_json
+        end
+
+        private
+
+        attr_reader :configuration, :request
+
+        def messages
+          [system_message, user_message]
+        end
+
+        def system_message
+          {
+            role: 'system',
+            content: 'You translate Rails model attributes faithfully and concisely.'
+          }
+        end
+
+        def user_message
+          {
+            role: 'user',
+            content: prompt
+          }
+        end
+
+        def prompt
+          <<~PROMPT
+            Translate the following model attribute.
+
+            Model: #{request.fetch(:model_name)}
+            Attribute: #{request.fetch(:attribute_name)}
+            Source locale: #{request.fetch(:source_locale)}
+            Target locale: #{request.fetch(:locale)}
+            Original content: #{request.fetch(:content)}
+          PROMPT
+        end
+
+        def tool_definition
+          {
+            type: 'function',
+            function: {
+              name: TOOL_NAME,
+              description: 'Return the translated text for the requested locale.',
+              parameters: tool_parameters
+            }
+          }
+        end
+
+        def tool_parameters
+          {
+            type: 'object',
+            properties: {
+              translated_text: {
+                type: 'string',
+                description: 'The translated version of the original content.'
+              }
+            },
+            required: ['translated_text'],
+            additionalProperties: false
+          }
+        end
+
+        def tool_choice
+          {
+            type: 'function',
+            function: { name: TOOL_NAME }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/purizumu/engines/xai/response_parser.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Purizumu
+  module Engines
+    class Xai
+      # Extracts the required tool payload from xAI responses.
+      class ResponseParser
+        def initialize(response:)
+          @response = response
+        end
+
+        def translated_text
+          raise TranslationError, failure_message if response_error?
+
+          extract_translation(parsed_body)
+        rescue JSON::ParserError => e
+          raise TranslationError, "Unable to parse xAI response: #{e.message}"
+        rescue KeyError => e
+          raise TranslationError, "xAI response missing translation payload: #{e.message}"
+        end
+
+        private
+
+        attr_reader :response
+
+        def parsed_body
+          @parsed_body ||= JSON.parse(response.body)
+        end
+
+        def response_error?
+          !response.is_a?(Net::HTTPSuccess)
+        end
+
+        def failure_message
+          "xAI request failed with status #{response.code}"
+        end
+
+        def extract_translation(body)
+          tool_call = body.dig('choices', 0, 'message', 'tool_calls', 0, 'function')
+          raise TranslationError, missing_tool_message unless tool_call
+
+          arguments = JSON.parse(tool_call.fetch('arguments'))
+          translation = arguments.fetch('translated_text').to_s
+          raise TranslationError, empty_translation_message if translation.empty?
+
+          translation
+        end
+
+        def missing_tool_message
+          'xAI response did not include the required translation tool call'
+        end
+
+        def empty_translation_message
+          'xAI response returned an empty translation'
+        end
+      end
+    end
+  end
+end

data/lib/purizumu/engines/xai.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Purizumu
+  module Engines
+    # Translation engine that uses xAI and forces a function tool response.
+    class Xai
+      TOOL_NAME = 'return_translation'
+
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def translate(model_name:, attribute_name:, content:, locale:, source_locale:)
+        validate_configuration!
+
+        response = transport.call(
+          uri,
+          request_headers,
+          request_body(model_name:, attribute_name:, content:, locale:, source_locale:)
+        )
+
+        ResponseParser.new(response:).translated_text
+      end
+
+      private
+
+      attr_reader :configuration
+
+      def validate_configuration!
+        if configuration.key.to_s.empty?
+          raise ConfigurationError, 'Purizumu xAI engine requires config.key'
+        end
+        return unless configuration.model.to_s.empty?
+
+        raise ConfigurationError, 'Purizumu xAI engine requires config.model'
+      end
+
+      def uri
+        base_url = configuration.base_url
+        base = base_url.end_with?('/') ? base_url : "#{base_url}/"
+        URI.join(base, 'chat/completions')
+      end
+
+      def request_headers
+        {
+          'Authorization' => "Bearer #{configuration.key}",
+          'Content-Type' => 'application/json'
+        }
+      end
+
+      def request_body(model_name:, attribute_name:, content:, locale:, source_locale:)
+        request = { model_name:, attribute_name:, content:, locale:, source_locale: }
+        PayloadBuilder.new(configuration:, request:).to_json
+      end
+
+      def transport
+        configuration.transport || method(:default_transport)
+      end
+
+      def default_transport(uri, headers, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+
+        request = Net::HTTP::Post.new(uri)
+        headers.each { |key, value| request[key] = value }
+        request.body = body
+
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/purizumu/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Purizumu
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class TranslationError < Error; end
+  class UnsupportedEngineError < Error; end
+end

data/lib/purizumu/model_extensions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Purizumu
+  # Adds the class-level DSL for declaring translated attributes.
+  module ModelExtensions
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Defines translated attribute readers on Active Record models.
+    module ClassMethods
+      def attribute_translation(*attribute_names)
+        attribute_names.flatten.each do |attribute_name|
+          define_method(attribute_name) do
+            Purizumu.translate_attribute(self, attribute_name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/purizumu/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+require 'generators/purizumu/install/install_generator'
+
+module Purizumu
+  # Hooks Purizumu into Rails so models can use the translation DSL.
+  class Railtie < Rails::Railtie
+    initializer 'purizumu.active_record' do
+      ActiveSupport.on_load(:active_record) do
+        include Purizumu::ModelExtensions
+      end
+    end
+  end
+end

data/lib/purizumu/translation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Purizumu
+  # Active Record model that persists generated translations by record and locale.
+  class Translation < ActiveRecord::Base
+    self.table_name = 'purizumu_translations'
+
+    validates :attribute_name, :content, :locale, :model_class_name, :record_id, presence: true
+    validates :locale, uniqueness: { scope: %i[model_class_name record_id attribute_name] }
+  end
+end

data/lib/purizumu/translator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Purizumu
+  # Resolves a translated attribute, generating and caching it on demand.
+  class Translator
+    def initialize(record:, attribute_name:, locale:)
+      @record = record
+      @attribute_name = attribute_name.to_s
+      @locale = locale.to_s
+    end
+
+    def call
+      return source_content if source_content.nil? || source_content == ''
+
+      existing_translation&.content || create_translation!.content
+    end
+
+    private
+
+    attr_reader :attribute_name, :locale, :record
+
+    def create_translation!
+      Translation.find_or_create_by!(
+        model_class_name: record.class.name,
+        record_id: record.id,
+        attribute_name: attribute_name,
+        locale: locale
+      ) do |translation|
+        translation.content = translated_content
+      end
+    end
+
+    def existing_translation
+      @existing_translation ||= Translation.find_by(
+        model_class_name: record.class.name,
+        record_id: record.id,
+        attribute_name: attribute_name,
+        locale: locale
+      )
+    end
+
+    def translated_content
+      return source_content if locale == source_locale
+
+      Purizumu.engine.translate(
+        model_name: record.class.name,
+        attribute_name: attribute_name,
+        content: source_content,
+        locale: locale,
+        source_locale: source_locale
+      )
+    end
+
+    def source_content
+      record.read_attribute(attribute_name)
+    end
+
+    def source_locale
+      Purizumu.configuration.resolved_source_locale
+    end
+  end
+end

data/lib/purizumu/version.rb

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

data/lib/purizumu.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'i18n'
+require 'json'
+require 'net/http'
+require 'uri'
+
+require 'purizumu/version'
+require 'purizumu/errors'
+require 'purizumu/configuration'
+require 'purizumu/engines/xai'
+require 'purizumu/engines/xai/payload_builder'
+require 'purizumu/engines/xai/response_parser'
+require 'purizumu/translation'
+require 'purizumu/model_extensions'
+require 'purizumu/translator'
+require 'purizumu/railtie' if defined?(Rails::Railtie)
+
+# Entry point and global configuration for Purizumu translations.
+module Purizumu
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def translate_attribute(record, attribute_name, locale: I18n.locale)
+      Translator.new(record: record, attribute_name: attribute_name, locale: locale).call
+    end
+
+    def engine
+      engine_name = configuration.engine.to_sym
+
+      case engine_name
+      when :xai
+        Engines::Xai.new(configuration: configuration)
+      else
+        raise UnsupportedEngineError, "Unsupported translation engine: #{engine_name}"
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.include(Purizumu::ModelExtensions) if defined?(ActiveRecord::Base)

data/spec/purizumu/configuration_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Purizumu::Configuration do
+  subject(:config) { described_class.new }
+
+  before do
+    Purizumu.configure do |config|
+      config.engine = :xai
+      config.key = 'secret'
+      config.model = 'grok-4.20-reasoning'
+      config.source_locale = :ja
+    end
+  end
+
+  it { expect(config.engine).to eq(:xai) }
+  it { expect(config.base_url).to eq('https://api.x.ai/v1') }
+  it { expect(config.resolved_source_locale).to eq('en') }
+
+  describe '.configure' do
+    subject(:configured) { Purizumu.configuration }
+
+    it { expect(configured.key).to eq('secret') }
+    it { expect(configured.model).to eq('grok-4.20-reasoning') }
+    it { expect(configured.resolved_source_locale).to eq('ja') }
+  end
+
+  it 'raises for unsupported engines' do
+    Purizumu.configure { |config| config.engine = :bogus }
+
+    expect { Purizumu.engine }.to raise_error(Purizumu::UnsupportedEngineError, /bogus/)
+  end
+end

data/spec/purizumu/engines/xai_spec.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Purizumu::Engines::Xai do
+  subject(:translate_call) do
+    engine.translate(
+      model_name: 'Gem',
+      attribute_name: 'human_name',
+      content: 'Prism',
+      locale: 'jp',
+      source_locale: 'en'
+    )
+  end
+
+  let(:transport) { instance_spy(Proc) }
+  let(:captured_request) { {} }
+  let(:configuration) do
+    Purizumu::Configuration.new.tap do |config|
+      config.key = 'token'
+      config.model = 'grok-test'
+      config.transport = transport
+    end
+  end
+  let(:engine) { described_class.new(configuration: configuration) }
+
+  describe '#translate' do
+    before do
+      allow(transport).to receive(:call) do |uri, headers, body|
+        captured_request[:uri] = uri
+        captured_request[:headers] = headers
+        captured_request[:body] = body
+        successful_translation_response
+      end
+    end
+
+    it 'returns the translated text' do
+      expect(translate_call).to eq('プリズム')
+    end
+
+    it 'calls the xAI chat completions endpoint' do
+      translate_call
+
+      expect(request_uri.to_s).to eq('https://api.x.ai/v1/chat/completions')
+    end
+
+    it 'sends the authorization header' do
+      translate_call
+
+      expect(request_headers['Authorization']).to eq('Bearer token')
+    end
+
+    it 'forces the translation tool choice' do
+      translate_call
+
+      expect(parsed_request_body['tool_choice']).to eq(
+        { 'type' => 'function', 'function' => { 'name' => 'return_translation' } }
+      )
+    end
+
+    it 'requires the translated_text tool parameter' do
+      translate_call
+
+      required = parsed_request_body['tools'].first.dig('function', 'parameters', 'required')
+      expect(required).to eq(['translated_text'])
+    end
+
+    it 'raises when key is missing' do
+      configuration.key = nil
+
+      expect { translate_call }.to raise_error(Purizumu::ConfigurationError, /config.key/)
+    end
+
+    it 'raises when model is missing' do
+      configuration.model = nil
+
+      expect { translate_call }.to raise_error(Purizumu::ConfigurationError, /config.model/)
+    end
+
+    it 'raises when the response does not contain a tool call' do
+      allow(transport).to receive(:call).and_return(response_with_body(choices: [{ message: {} }]))
+
+      expect { translate_call }.to raise_error(
+        Purizumu::TranslationError,
+        /required translation tool call/
+      )
+    end
+
+    it 'raises when the response body is invalid json' do
+      allow(transport).to receive(:call).and_return(response_with_raw_body(Net::HTTPOK, 'not json'))
+
+      expect { translate_call }.to raise_error(Purizumu::TranslationError, /Unable to parse/)
+    end
+
+    it 'raises when the http status is unsuccessful' do
+      bad_response = response_with_raw_body(Net::HTTPBadRequest, { error: 'bad request' }.to_json,
+                                            code: '400', message: 'Bad Request')
+      allow(transport).to receive(:call).and_return(bad_response)
+
+      expect { translate_call }.to raise_error(Purizumu::TranslationError, /status 400/)
+    end
+
+    it 'raises when translated_text is missing' do
+      allow(transport).to receive(:call).and_return(response_with_body(missing_translation_body))
+
+      expect { translate_call }.to raise_error(
+        Purizumu::TranslationError,
+        /missing translation payload/
+      )
+    end
+  end
+
+  def request_uri
+    captured_request.fetch(:uri)
+  end
+
+  def request_headers
+    captured_request.fetch(:headers)
+  end
+
+  def parsed_request_body
+    JSON.parse(captured_request.fetch(:body))
+  end
+
+  def response_with_body(body)
+    response_with_raw_body(Net::HTTPOK, body.to_json)
+  end
+
+  def successful_translation_response
+    response_with_body(
+      choices: [
+        {
+          message: {
+            tool_calls: [
+              {
+                function: {
+                  arguments: { translated_text: 'プリズム' }.to_json
+                }
+              }
+            ]
+          }
+        }
+      ]
+    )
+  end
+
+  def missing_translation_body
+    { choices: [{ message: { tool_calls: [{ function: { arguments: {}.to_json } }] } }] }
+  end
+
+  def response_with_raw_body(klass, body, code: '200', message: 'OK')
+    klass.new('1.1', code, message).tap do |response|
+      allow(response).to receive(:body).and_return(body)
+    end
+  end
+end

data/spec/purizumu/generators/install_generator_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'generators/purizumu/install/install_generator'
+
+RSpec.describe Purizumu::Generators::InstallGenerator do
+  let(:destination_root) { File.expand_path('../../tmp/generator', __dir__) }
+  let(:migration_path) do
+    Dir[File.join(destination_root, 'db/migrate/*_create_purizumu_translations.rb')].first
+  end
+  let(:migration_content) { File.read(migration_path) }
+
+  before do
+    FileUtils.rm_rf(destination_root)
+    FileUtils.mkdir_p(destination_root)
+    described_class.start([], destination_root:)
+  end
+
+  it 'creates the install migration' do
+    expect(migration_path).to be_present
+  end
+
+  it 'includes the translation table definition' do
+    expect(migration_content).to include('create_table :purizumu_translations')
+  end
+
+  it 'includes the record id column' do
+    expect(migration_content).to include('t.bigint :record_id, null: false')
+  end
+
+  it 'includes the unique composite index' do
+    expect(migration_content).to include('%i[model_class_name record_id attribute_name locale]')
+  end
+
+  it 'marks the composite index as unique' do
+    expect(migration_content).to include('unique: true')
+  end
+end

data/spec/purizumu/translator_spec.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Purizumu::Translator do
+  subject(:translated_name) { record.human_name }
+
+  before do
+    stub_const('GemRecord', Class.new(ActiveRecord::Base) do
+      self.table_name = 'gems'
+
+      attribute_translation :human_name
+    end)
+  end
+
+  let!(:record) { GemRecord.create!(human_name: 'Prism') }
+  let(:translation_scope) do
+    Purizumu::Translation.where(
+      model_class_name: 'GemRecord',
+      record_id: record.id,
+      attribute_name: 'human_name'
+    )
+  end
+  let(:existing_translation_attributes) do
+    {
+      model_class_name: 'GemRecord',
+      record_id: record.id,
+      attribute_name: 'human_name',
+      locale: 'jp',
+      content: 'プリズム'
+    }
+  end
+  let(:engine) { instance_double(Purizumu::Engines::Xai, translate: 'Prisma') }
+
+  describe '#call' do
+    before do
+      allow(Purizumu).to receive(:engine).and_call_original
+    end
+
+    it 'returns the original content for the source locale' do
+      I18n.locale = :en
+
+      expect(translated_name).to eq('Prism')
+    end
+
+    it 'stores the source locale translation' do
+      I18n.locale = :en
+      translated_name
+
+      expect(translation_scope.find_by!(locale: 'en').content).to eq('Prism')
+    end
+
+    it 'returns an existing translation' do
+      create_existing_translation
+      I18n.locale = :jp
+
+      expect(translated_name).to eq('プリズム')
+    end
+
+    it 'does not invoke the engine for an existing translation' do
+      create_existing_translation
+      I18n.locale = :jp
+      translated_name
+
+      expect(Purizumu).not_to have_received(:engine)
+    end
+
+    it 'returns a generated translation when missing' do
+      engine = instance_double(Purizumu::Engines::Xai)
+      allow(Purizumu).to receive(:engine).and_return(engine)
+      allow(engine).to receive(:translate).and_return('Призма')
+
+      I18n.locale = :ru
+
+      expect(translated_name).to eq('Призма')
+    end
+
+    it 'persists a generated translation when missing' do
+      engine = instance_double(Purizumu::Engines::Xai, translate: 'Призма')
+      allow(Purizumu).to receive(:engine).and_return(engine)
+
+      I18n.locale = :ru
+      translated_name
+
+      expect(translation_scope.find_by!(locale: 'ru').content).to eq('Призма')
+    end
+
+    it 'passes model and locale details to the engine' do
+      allow(Purizumu).to receive(:engine).and_return(engine)
+      I18n.locale = :es
+      translated_name
+
+      expect(engine).to have_received(:translate).with(expected_engine_arguments)
+    end
+
+    it 'returns blank content without creating a translation' do
+      blank_record = GemRecord.create!(human_name: '')
+
+      I18n.locale = :jp
+
+      expect(blank_record.human_name).to eq('')
+    end
+
+    it 'does not create a translation for blank content' do
+      blank_record = GemRecord.create!(human_name: '')
+
+      I18n.locale = :jp
+      blank_record.human_name
+
+      expect(Purizumu::Translation.where(record_id: blank_record.id)).to be_empty
+    end
+  end
+
+  def create_existing_translation
+    Purizumu::Translation.create!(existing_translation_attributes)
+  end
+
+  def expected_engine_arguments
+    {
+      model_name: 'GemRecord',
+      attribute_name: 'human_name',
+      content: 'Prism',
+      locale: 'es',
+      source_locale: 'en'
+    }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+require 'bundler/setup'
+require 'active_record'
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'rails'
+require 'rails/generators'
+require 'rspec'
+
+require 'purizumu'
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    I18n.available_locales = %i[en es jp ru]
+    I18n.default_locale = :en
+
+    ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+
+    ActiveRecord::Schema.define do
+      suppress_messages do
+        create_table :gems, force: true do |t|
+          t.string :human_name
+        end
+
+        create_table :purizumu_translations, force: true do |t|
+          t.string :model_class_name, null: false
+          t.bigint :record_id, null: false
+          t.string :attribute_name, null: false
+          t.string :locale, null: false
+          t.text :content, null: false
+          t.timestamps null: false
+        end
+
+        add_index :purizumu_translations,
+                  %i[model_class_name record_id attribute_name locale],
+                  unique: true,
+                  name: 'index_purizumu_translations_uniqueness'
+      end
+    end
+  end
+
+  config.before do
+    Purizumu.reset_configuration!
+    I18n.locale = I18n.default_locale
+    Purizumu::Translation.delete_all
+  end
+
+  config.after(:suite) do
+    ActiveRecord::Base.connection.disconnect!
+  end
+end

data/spec/tmp/generator/db/migrate/20260412193408_create_purizumu_translations.rb

@@ -0,0 +1,18 @@
+class CreatePurizumuTranslations < ActiveRecord::Migration[7.0]
+  def change
+    create_table :purizumu_translations do |t|
+      t.string :model_class_name, null: false
+      t.bigint :record_id, null: false
+      t.string :attribute_name, null: false
+      t.string :locale, null: false
+      t.text :content, null: false
+
+      t.timestamps
+    end
+
+    add_index :purizumu_translations,
+              %i[model_class_name record_id attribute_name locale],
+              unique: true,
+              name: "index_purizumu_translations_uniqueness"
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: purizumu
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- OpenAI Codex
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Purizumu lazily translates Rails model attributes into multiple locales
+  and caches them in the database.
+email:
+- noreply@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/generators/purizumu/install/install_generator.rb
+- lib/generators/purizumu/install/templates/create_purizumu_translations.rb.erb
+- lib/purizumu.rb
+- lib/purizumu/configuration.rb
+- lib/purizumu/engines/xai.rb
+- lib/purizumu/engines/xai/payload_builder.rb
+- lib/purizumu/engines/xai/response_parser.rb
+- lib/purizumu/errors.rb
+- lib/purizumu/model_extensions.rb
+- lib/purizumu/railtie.rb
+- lib/purizumu/translation.rb
+- lib/purizumu/translator.rb
+- lib/purizumu/version.rb
+- spec/purizumu/configuration_spec.rb
+- spec/purizumu/engines/xai_spec.rb
+- spec/purizumu/generators/install_generator_spec.rb
+- spec/purizumu/translator_spec.rb
+- spec/spec_helper.rb
+- spec/tmp/generator/db/migrate/20260412193408_create_purizumu_translations.rb
+homepage: https://example.com/purizumu
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://example.com/purizumu
+  source_code_uri: https://example.com/purizumu
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Auto-translate Rails model attributes and persist the results.
+test_files: []