internationalize 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ba5df71bafb02b68108aed602ac75ad4ced036109e49dbd40dc90354a7c351a
+  data.tar.gz: d39b4232e8b76511d1a409d6848fa98e8f60f8f9523b62985c467cb2767ec7e3
+SHA512:
+  metadata.gz: 8ff4adb5021405380a123cc1cc06b8dd3818851e32570ae90e7bdf776f566bbc9ff6504ab26960dae909109550444875aaca42d3cf988ae4393b18c05628e292
+  data.tar.gz: 8d2643b882281a39f0446d274b25321be03909c2ba41510a75a4e498918fc0ee37a59abae42e373e246a4d1b1f1ebeefdb5ec9e12e29d8a81a13c3d05f9478a6

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-11-29
+
+### Added
+
+- Initial release
+- `Internationalize::Model` mixin for ActiveRecord models
+- `international` declaration for translatable attributes
+- Locale-specific accessors (`title_en`, `title_de`, etc.)
+- Query methods:
+  - `international(attr: value)` - exact match queries
+  - `international(attr: value, match: :partial)` - case-insensitive LIKE search
+  - `international_not()` - exclusion queries
+  - `international_order()` - order by translated attribute
+  - `translated()` - find records with translations
+  - `untranslated()` - find records missing translations
+- Creation helpers:
+  - `international_create!` / `international_create` / `international_new`
+  - Support both hash format `title: { en: "Hello" }` and direct string `title: "Hello"` (uses current locale)
+- Instance helpers:
+  - `set_translation(attr, locale, value)`
+  - `translation_for(attr, locale)`
+  - `translated?(attr, locale)`
+  - `translated_locales(attr)`
+- Fallback to default locale when translation missing (configurable)
+- SQLite adapter using `json_extract()`
+- PostgreSQL adapter using `->>` operator
+- MySQL 8+ adapter using `->>` operator (supports mysql2 and trilogy gems)
+- Rails generator: `rails g internationalize:translation Model attr1 attr2`
+- Warning when JSON columns are missing `default: {}`
+- Security: locale parameter sanitization to prevent SQL injection

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Sampo Kuokkanen
+
+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,232 @@
+# Internationalize
+
+Lightweight, performant internationalization for Rails with JSON column storage.
+
+## Why Internationalize?
+
+Unlike Globalize or Mobility which use separate translation tables requiring JOINs, Internationalize stores translations inline using JSON columns. This means:
+
+- **No JOINs** - translations live in the same table
+- **No N+1 queries** - data is always loaded with the record
+- **Direct method dispatch** - no `method_missing` overhead
+- **Multi-database support** - works with SQLite, PostgreSQL, and MySQL
+- **Visible in schema.rb** - translated fields appear directly in your model's schema
+
+## Supported Databases
+
+| Database | JSON Column | Query Syntax |
+|----------|-------------|--------------|
+| SQLite 3.38+ | `json` | `json_extract()` |
+| PostgreSQL 9.4+ | `json` / `jsonb` | `->>` operator |
+| MySQL 8.0+ | `json` | `->>` operator |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "internationalize"
+```
+
+## Usage
+
+### 1. Generate a migration
+
+```bash
+rails generate internationalize:translation Article title description
+```
+
+This creates a migration adding `title_translations` and `description_translations` JSON columns with `default: {}`.
+
+**Important:** JSON columns must have `default: {}` set. The generator handles this automatically, but if writing migrations manually:
+
+```ruby
+add_column :articles, :title_translations, :json, default: {}
+```
+
+### 2. Include the model mixin
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title, :description
+end
+```
+
+### 3. Use translations
+
+```ruby
+# Set via current locale (I18n.locale)
+article.title = "Hello World"
+
+# Set for specific locale
+article.title_en = "Hello World"
+article.title_de = "Hallo Welt"
+
+# Read via current locale
+article.title  # => "Hello World" (when I18n.locale == :en)
+
+# Read specific locale
+article.title_de  # => "Hallo Welt"
+
+# Access raw translations
+article.title_translations  # => {"en" => "Hello World", "de" => "Hallo Welt"}
+```
+
+### Creating Records
+
+Use the helper methods for a cleaner syntax when creating records with translations:
+
+```ruby
+# Create with multiple locales using a hash
+Article.international_create!(
+  title: { en: "Hello World", de: "Hallo Welt" },
+  description: { en: "A greeting" },
+  status: "published"  # non-translated attributes work normally
+)
+
+# Or use direct assignment for current locale (I18n.locale)
+I18n.locale = :de
+Article.international_create!(title: "Achtung!")  # Sets title_de
+
+# Mix both styles
+Article.international_create!(
+  title: "Hello",  # Current locale only
+  description: { en: "English", de: "German" }  # Multiple locales
+)
+
+# Build without saving
+article = Article.international_new(title: "Hello")
+article.save!
+
+# Non-bang version returns unsaved record on validation failure
+article = Article.international_create(title: { en: "Hello" })
+```
+
+### Querying
+
+All query methods default to the current `I18n.locale` and return ActiveRecord relations that can be chained with standard AR methods.
+
+```ruby
+# Exact match on translation (uses current locale by default)
+Article.international(title: "Hello World")
+Article.international(title: "Hallo Welt", locale: :de)
+
+# Partial match / search (case-insensitive LIKE)
+Article.international(title: "hello", match: :partial)
+Article.international(title: "Hello", match: :partial, case_sensitive: true)
+Article.international(title: "hallo", match: :partial, locale: :de)
+
+# Exclude matches
+Article.international_not(title: "Draft")
+Article.international_not(title: "Entwurf", locale: :de)
+
+# Order by translation
+Article.international_order(:title)
+Article.international_order(:title, :desc)
+Article.international_order(:title, :asc, locale: :de)
+
+# Find translated/untranslated records
+Article.translated(:title)
+Article.translated(:title, locale: :de)
+Article.untranslated(:title, locale: :de)
+
+# Chain with ActiveRecord methods
+Article.international(title: "Hello World")
+       .where(published: true)
+       .includes(:author)
+       .limit(10)
+
+# Combine queries
+Article.international(title: "hello", match: :partial)
+       .where(status: "published")
+       .merge(Article.international_order(:title, :desc))
+
+# Query across multiple locales
+Article.international(title: "Hello World", locale: :en)
+       .merge(Article.international(title: "Hallo Welt", locale: :de))
+```
+
+### Helper Methods
+
+```ruby
+# Check if translation exists
+article.translated?(:title, :de)  # => true/false
+
+# Get all translated locales for an attribute
+article.translated_locales(:title)  # => [:en, :de]
+
+# Set/get translation for specific locale
+article.set_translation(:title, :de, "Hallo Welt")
+article.translation_for(:title, :de)  # => "Hallo Welt"
+```
+
+### Fallbacks
+
+By default, Internationalize falls back to the default locale when a translation is missing:
+
+```ruby
+article.title_en = "Hello"
+article.title_de  # => nil
+
+I18n.locale = :de
+article.title  # => "Hello" (falls back to :en)
+```
+
+Disable fallbacks:
+
+```ruby
+international :title, fallback: false
+```
+
+## Configuration
+
+```ruby
+# config/initializers/internationalize.rb
+Internationalize.configure do |config|
+  config.fallback_locale = :en
+  config.available_locales = [:en, :de, :fr]
+end
+```
+
+## Performance Comparison
+
+Benchmark with 1000 records, 2 translated attributes (title + body), 3 locales:
+
+| Metric | Internationalize | Mobility (Table) | Improvement |
+|--------|------------------|------------------|-------------|
+| Storage | 172 KB | 332 KB | **48% smaller** |
+| Create | 0.27s | 2.1s | **7.8x faster** |
+| Read all | 0.005s | 0.37s | **74x faster** |
+| Query (match) | 0.001s | 0.01s | **10x faster** |
+
+## Trade-offs
+
+### Pros
+- **Faster reads** - No JOINs needed, translations are inline
+- **Less storage** - No separate translation tables with foreign keys and indices
+- **Simpler schema** - Everything in one table
+
+### Cons
+- **Schema changes required** - Each translated attribute needs a JSON column added to the table
+- **Migration complexity** - Adding translations to existing tables requires data migration
+- **JSON column support** - Requires SQLite 3.38+, PostgreSQL 9.4+, or MySQL 8.0+
+
+### When to use Internationalize
+- New projects where you can design the schema upfront
+- Applications with heavy read workloads
+- When you need maximum query performance
+
+### When to consider Mobility
+
+For table-based translation storage, consider [Mobility](https://github.com/shioyama/mobility) instead:
+
+- Existing projects with large tables where adding columns is expensive
+- When you need to add translations without modifying existing table schemas
+- Applications that rarely query by translated content
+
+Mobility's table backend stores translations in separate tables with JOINs, which trades query performance for schema flexibility.
+
+## License
+
+MIT License. See LICENSE.txt.

data/lib/generators/internationalize/translation/templates/add_translations_migration.rb.erb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+<% attributes.each do |attr| -%>
+    add_column :<%= table_name %>, :<%= attr %>_translations, :json, default: {}
+<% end -%>
+  end
+end

data/lib/generators/internationalize/translation_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Internationalize
+  module Generators
+    class TranslationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("translation/templates", __dir__)
+
+      argument :model_name, type: :string, desc: "The model to add translations to"
+      argument :attributes, type: :array, desc: "Attributes to make translatable"
+
+      desc "Generates a migration to add translation columns to a model"
+
+      def create_migration_file
+        migration_template(
+          "add_translations_migration.rb.erb",
+          "db/migrate/add_#{attributes.join("_and_")}_translations_to_#{table_name}.rb",
+        )
+      end
+
+      private
+
+      def table_name
+        model_name.tableize.tr("/", "_")
+      end
+
+      def migration_class_name
+        "Add#{attributes.map(&:camelize).join("And")}TranslationsTo#{model_name.gsub("::", "").pluralize}"
+      end
+    end
+  end
+end

data/lib/internationalize/adapters/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Internationalize
+  module Adapters
+    # Base adapter class defining the interface for database-specific SQL generation
+    class Base
+      # Sanitize a locale for safe SQL interpolation
+      # Only allows alphanumeric characters, underscores, and hyphens
+      #
+      # @param locale [String, Symbol] the locale key
+      # @return [String] sanitized locale safe for SQL interpolation
+      def sanitize_locale(locale)
+        locale.to_s.gsub(/[^a-zA-Z0-9_\-]/, "")
+      end
+
+      # Extract a value from a JSON column
+      #
+      # @param column [String] the JSON column name
+      # @param locale [String, Symbol] the locale key
+      # @return [String] SQL fragment for extracting the value
+      def json_extract(column, locale)
+        raise NotImplementedError, "#{self.class} must implement #json_extract"
+      end
+
+      # Generate a case-insensitive LIKE condition
+      #
+      # @param column [String] the JSON column name
+      # @param locale [String, Symbol] the locale key
+      # @return [Array<String, Symbol>] SQL fragment and pattern type
+      def like_insensitive(column, locale)
+        raise NotImplementedError, "#{self.class} must implement #like_insensitive"
+      end
+
+      # Generate a case-sensitive LIKE/GLOB condition
+      #
+      # @param column [String] the JSON column name
+      # @param locale [String, Symbol] the locale key
+      # @return [Array<String, Symbol>] SQL fragment and pattern type
+      def like_sensitive(column, locale)
+        raise NotImplementedError, "#{self.class} must implement #like_sensitive"
+      end
+
+      # Wrap a LIKE pattern with wildcards
+      # Uses ActiveRecord's built-in sanitize_sql_like for escaping
+      #
+      # @param term [String] the search term
+      # @return [String] pattern with wildcards
+      def like_pattern(term)
+        "%#{ActiveRecord::Base.sanitize_sql_like(term.to_s)}%"
+      end
+
+      # Wrap a term with pattern wildcards for case-sensitive search
+      # Default implementation uses LIKE pattern (PostgreSQL/MySQL)
+      # SQLite overrides this to use GLOB pattern
+      #
+      # @param term [String] the search term
+      # @return [String] pattern with wildcards
+      def glob_pattern(term)
+        like_pattern(term)
+      end
+    end
+  end
+end

data/lib/internationalize/adapters/mysql.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Internationalize
+  module Adapters
+    # MySQL 8+ specific SQL generation for JSON queries
+    #
+    # Uses ->> operator for text extraction from JSON columns
+    # LIKE for case-insensitive matching (default with utf8mb4 collation)
+    # LIKE BINARY for case-sensitive matching
+    class MySQL < Base
+      # Extract a value from a JSON column using ->> operator
+      #
+      # @param column [String] the JSON column name
+      # @param locale [String, Symbol] the locale key
+      # @return [String] SQL fragment
+      def json_extract(column, locale)
+        "#{column}->>'$.#{sanitize_locale(locale)}'"
+      end
+
+      # Case-insensitive search using LIKE (default behavior with utf8mb4)
+      #
+      # @return [Array<String, Symbol>] SQL condition and pattern type
+      def like_insensitive(column, locale)
+        ["#{json_extract(column, locale)} LIKE ?", :like]
+      end
+
+      # Case-sensitive search using LIKE BINARY
+      #
+      # @return [Array<String, Symbol>] SQL condition and pattern type
+      def like_sensitive(column, locale)
+        ["#{json_extract(column, locale)} LIKE BINARY ?", :like]
+      end
+    end
+  end
+end

data/lib/internationalize/adapters/postgresql.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Internationalize
+  module Adapters
+    # PostgreSQL-specific SQL generation for JSON/JSONB queries
+    #
+    # Uses ->> operator for text extraction from JSON/JSONB columns
+    # ILIKE for case-insensitive matching
+    # LIKE for case-sensitive matching
+    class PostgreSQL < Base
+      # Extract a value from a JSON/JSONB column using ->> operator
+      #
+      # @param column [String] the JSON column name
+      # @param locale [String, Symbol] the locale key
+      # @return [String] SQL fragment
+      def json_extract(column, locale)
+        "#{column}->>'#{sanitize_locale(locale)}'"
+      end
+
+      # Case-insensitive search using ILIKE
+      #
+      # @return [Array<String, Symbol>] SQL condition and pattern type
+      def like_insensitive(column, locale)
+        ["#{json_extract(column, locale)} ILIKE ?", :like]
+      end
+
+      # Case-sensitive search using LIKE
+      #
+      # @return [Array<String, Symbol>] SQL condition and pattern type
+      def like_sensitive(column, locale)
+        ["#{json_extract(column, locale)} LIKE ?", :like]
+      end
+    end
+  end
+end

data/lib/internationalize/adapters/sqlite.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Internationalize
+  module Adapters
+    # SQLite-specific SQL generation for JSON queries
+    #
+    # Uses json_extract() function (SQLite 3.38+)
+    # LIKE for case-insensitive matching (default for ASCII)
+    # GLOB for case-sensitive matching
+    class SQLite < Base
+      # Extract a value from a JSON column using json_extract
+      #
+      # @param column [String] the JSON column name
+      # @param locale [String, Symbol] the locale key
+      # @return [String] SQL fragment
+      def json_extract(column, locale)
+        "json_extract(#{column}, '$.#{sanitize_locale(locale)}')"
+      end
+
+      # Case-insensitive search using LIKE (default for ASCII in SQLite)
+      #
+      # @return [Array<String, Symbol>] SQL condition and pattern type
+      def like_insensitive(column, locale)
+        ["#{json_extract(column, locale)} LIKE ? ESCAPE '\\'", :like]
+      end
+
+      # Case-sensitive search using GLOB
+      #
+      # @return [Array<String, Symbol>] SQL condition and pattern type
+      def like_sensitive(column, locale)
+        ["#{json_extract(column, locale)} GLOB ?", :glob]
+      end
+
+      # GLOB pattern with wildcards
+      # GLOB uses * and ? instead of % and _, and is case-sensitive
+      #
+      # @param term [String] the search term
+      # @return [String] GLOB pattern with wildcards
+      def glob_pattern(term)
+        # Escape GLOB special characters: * ? [ ]
+        escaped = term.to_s.gsub(/[*?\[\]]/) { |m| "[#{m}]" }
+        "*#{escaped}*"
+      end
+    end
+  end
+end

data/lib/internationalize/adapters.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "adapters/base"
+require_relative "adapters/sqlite"
+require_relative "adapters/postgresql"
+require_relative "adapters/mysql"
+
+module Internationalize
+  module Adapters
+    class << self
+      # Returns the appropriate SQL generator for the current database
+      # Detection is based on ActiveRecord's connection adapter name
+      #
+      # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      # @return [Internationalize::Adapters::Base] the SQL generator
+      def resolve(connection = ActiveRecord::Base.connection)
+        case connection.adapter_name.downcase
+        when /sqlite/
+          SQLite.new
+        when /postgres/
+          PostgreSQL.new
+        when /mysql|trilogy/
+          MySQL.new
+        else
+          raise UnsupportedAdapter, "Database adapter '#{connection.adapter_name}' is not supported. " \
+            "Supported adapters: sqlite, postgresql, mysql"
+        end
+      end
+    end
+
+    # Raised when an unsupported database adapter is detected
+    class UnsupportedAdapter < StandardError; end
+  end
+end

data/lib/internationalize/model.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+module Internationalize
+  # Mixin for ActiveRecord models to enable internationalization
+  #
+  # @example
+  #   class Article < ApplicationRecord
+  #     include Internationalize::Model
+  #     international :title, :description
+  #   end
+  #
+  #   # Querying
+  #   Article.international(title: "Hello")
+  #   Article.international(title: "hello", match: :partial)
+  #   Article.international_order(:title, :desc)
+  #
+  module Model
+    extend ActiveSupport::Concern
+
+    VALID_DIRECTIONS = ["ASC", "DESC"].freeze
+
+    included do
+      class_attribute :international_attributes, default: []
+    end
+
+    class_methods do
+      # Declares attributes as internationalized OR queries by translated attributes
+      #
+      # When called with Symbol arguments, declares attributes as internationalized:
+      #   international :title, :description
+      #   international :title, fallback: false
+      #
+      # When called with keyword arguments, queries translated attributes:
+      #   Article.international(title: "Hello")                      # exact match
+      #   Article.international(title: "Hello", locale: :de)         # exact match in German
+      #   Article.international(title: "hello", match: :partial)     # LIKE match (case-insensitive)
+      #   Article.international(title: "Hello", match: :partial, case_sensitive: true)
+      #
+      # @param attributes [Array<Symbol>] attributes to declare as internationalized
+      # @param fallback [Boolean] whether to fallback to default locale (default: true)
+      # @param locale [Symbol] locale to query (default: current locale)
+      # @param match [Symbol] :exact or :partial (default: :exact)
+      # @param case_sensitive [Boolean] for partial matching only (default: false)
+      # @param conditions [Hash] attribute => value pairs to query
+      #
+      def international(*attributes, fallback: true, locale: nil, match: :exact, case_sensitive: false, **conditions)
+        if attributes.any? && attributes.first.is_a?(Symbol) && conditions.empty?
+          # Declaration mode: international :title, :description
+          declare_international_attributes(attributes, fallback: fallback)
+        else
+          # Query mode: Article.international(title: "Hello")
+          international_query(conditions, locale: locale, match: match, case_sensitive: case_sensitive)
+        end
+      end
+
+      # Order by translated attribute
+      #
+      # @param attribute [Symbol] attribute to order by
+      # @param direction [Symbol] :asc or :desc (default: :asc)
+      # @param locale [Symbol] locale to order by (default: current locale)
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   Article.international_order(:title)
+      #   Article.international_order(:title, :desc)
+      #   Article.international_order(:title, :desc, locale: :de)
+      #
+      def international_order(attribute, direction = :asc, locale: nil)
+        unless international_attributes.include?(attribute.to_sym)
+          raise ArgumentError, "#{attribute} is not an international attribute. " \
+            "Use standard ActiveRecord methods for non-translated attributes."
+        end
+
+        locale ||= Internationalize.locale
+        direction = direction.to_s.upcase
+        direction = "ASC" unless VALID_DIRECTIONS.include?(direction)
+
+        adapter = Adapters.resolve(connection)
+        json_col = "#{attribute}_translations"
+        order(Arel.sql("#{adapter.json_extract(json_col, locale)} #{direction}"))
+      end
+
+      # Find records that have a translation for the given attributes
+      #
+      # @param attributes [Array<Symbol>] attributes to check
+      # @param locale [Symbol] locale to check (default: current locale)
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   Article.translated(:title)
+      #   Article.translated(:title, :description, locale: :de)
+      #
+      def translated(*attributes, locale: nil)
+        locale ||= Internationalize.locale
+        adapter = Adapters.resolve(connection)
+        scope = all
+
+        attributes.each do |attr|
+          next unless international_attributes.include?(attr.to_sym)
+
+          json_col = "#{attr}_translations"
+          extract = adapter.json_extract(json_col, locale)
+          scope = scope.where("#{extract} IS NOT NULL AND #{extract} != ''")
+        end
+
+        scope
+      end
+
+      # Find records missing a translation for the given attributes
+      #
+      # @param attributes [Array<Symbol>] attributes to check
+      # @param locale [Symbol] locale to check (default: current locale)
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   Article.untranslated(:title)
+      #   Article.untranslated(:title, locale: :de)
+      #
+      def untranslated(*attributes, locale: nil)
+        locale ||= Internationalize.locale
+        adapter = Adapters.resolve(connection)
+        scope = all
+
+        attributes.each do |attr|
+          next unless international_attributes.include?(attr.to_sym)
+
+          json_col = "#{attr}_translations"
+          extract = adapter.json_extract(json_col, locale)
+          scope = scope.where("#{extract} IS NULL OR #{extract} = ''")
+        end
+
+        scope
+      end
+
+      # Exclude records matching translated attribute conditions
+      #
+      # @param conditions [Hash] attribute => value pairs to exclude
+      # @param locale [Symbol] locale to use (default: current locale)
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   Article.international_not(title: "Draft")
+      #   Article.international_not(title: "Entwurf", locale: :de)
+      #
+      def international_not(locale: nil, **conditions)
+        locale ||= Internationalize.locale
+        adapter = Adapters.resolve(connection)
+        scope = all
+
+        conditions.each do |attr, value|
+          unless international_attributes.include?(attr.to_sym)
+            raise ArgumentError, "#{attr} is not an international attribute. " \
+              "Use standard ActiveRecord methods for non-translated attributes."
+          end
+
+          json_col = "#{attr}_translations"
+          extract = adapter.json_extract(json_col, locale)
+          scope = scope.where("#{extract} != ? OR #{extract} IS NULL", value)
+        end
+
+        scope
+      end
+
+      # Create a new instance with translated attributes in a cleaner format
+      #
+      # @param attributes [Hash] attributes including translations as nested hashes
+      # @return [ActiveRecord::Base] new unsaved instance
+      #
+      # @example
+      #   Article.international_new(
+      #     title: { en: "Hello", de: "Hallo" },
+      #     status: "published"
+      #   )
+      #
+      def international_new(attributes = {})
+        new(convert_international_attributes(attributes))
+      end
+
+      # Create and save a record with translated attributes
+      #
+      # @param attributes [Hash] attributes including translations as nested hashes
+      # @return [ActiveRecord::Base] the created record
+      #
+      # @example
+      #   Article.international_create(title: { en: "Hello", de: "Hallo" })
+      #
+      def international_create(attributes = {})
+        create(convert_international_attributes(attributes))
+      end
+
+      # Create and save a record with translated attributes, raising on failure
+      #
+      # @param attributes [Hash] attributes including translations as nested hashes
+      # @return [ActiveRecord::Base] the created record
+      # @raise [ActiveRecord::RecordInvalid] if validation fails
+      #
+      # @example
+      #   Article.international_create!(title: { en: "Hello", de: "Hallo" })
+      #
+      def international_create!(attributes = {})
+        create!(convert_international_attributes(attributes))
+      end
+
+      private
+
+      # Convert international attributes from clean format to internal format
+      #
+      # { title: { en: "Hello", de: "Hallo" } }
+      # becomes
+      # { title_translations: { "en" => "Hello", "de" => "Hallo" } }
+      #
+      # Also supports direct assignment using current locale:
+      # { title: "Achtung!" } with I18n.locale = :de
+      # becomes
+      # { title_translations: { "de" => "Achtung!" } }
+      #
+      def convert_international_attributes(attributes)
+        result = {}
+
+        attributes.each do |key, value|
+          if international_attributes.include?(key.to_sym)
+            result[:"#{key}_translations"] = if value.is_a?(Hash)
+              value.transform_keys(&:to_s)
+            else
+              { I18n.locale.to_s => value }
+            end
+          else
+            result[key] = value
+          end
+        end
+
+        result
+      end
+
+      # Declares attributes as internationalized
+      def declare_international_attributes(attributes, fallback:)
+        self.international_attributes = international_attributes | attributes.map(&:to_sym)
+
+        attributes.each do |attr|
+          warn_if_missing_default(attr)
+          define_translation_accessors(attr, fallback: fallback)
+          define_locale_accessors(attr)
+        end
+      end
+
+      # Warn if JSON column is missing default: {}
+      def warn_if_missing_default(attr)
+        return unless table_exists?
+
+        column = columns_hash["#{attr}_translations"]
+        return unless column
+        return if column.default.present?
+
+        warn("[Internationalize] WARNING: Column #{table_name}.#{attr}_translations " \
+          "is missing `default: {}`. This may cause errors. " \
+          "Add `default: {}` to your migration.")
+      end
+
+      # Query translated attributes with exact or partial matching
+      def international_query(conditions, locale:, match:, case_sensitive:)
+        locale ||= Internationalize.locale
+        adapter = Adapters.resolve(connection)
+        scope = all
+
+        conditions.each do |attr, value|
+          unless international_attributes.include?(attr.to_sym)
+            raise ArgumentError, "#{attr} is not an international attribute. " \
+              "Use standard ActiveRecord methods for non-translated attributes."
+          end
+
+          json_col = "#{attr}_translations"
+
+          scope = if match == :partial
+            if case_sensitive
+              sql, pattern_type = adapter.like_sensitive(json_col, locale)
+              pattern = pattern_type == :glob ? adapter.glob_pattern(value) : adapter.like_pattern(value)
+            else
+              sql, _ = adapter.like_insensitive(json_col, locale)
+              pattern = adapter.like_pattern(value)
+            end
+            scope.where(sql, pattern)
+          else
+            scope.where("#{adapter.json_extract(json_col, locale)} = ?", value)
+          end
+        end
+
+        scope
+      end
+
+      # Defines the main getter/setter for an attribute
+      def define_translation_accessors(attr, fallback:)
+        translations_column = "#{attr}_translations"
+
+        # Main getter - returns translation for current locale
+        # Cache default locale at definition time for faster fallback
+        default_locale_str = fallback ? Internationalize.default_locale.to_s : nil
+
+        define_method(attr) do |locale = nil|
+          locale_str = (locale || I18n.locale).to_s
+          translations = read_attribute(translations_column)
+          value = translations[locale_str]
+
+          # Short-circuit: return early if value exists or no fallback needed
+          return value if !fallback || !value.nil? || locale_str == default_locale_str
+
+          translations[default_locale_str]
+        end
+
+        # Main setter - sets translation for current locale
+        define_method("#{attr}=") do |value|
+          locale_str = I18n.locale.to_s
+          translations = read_attribute(translations_column)
+          translations[locale_str] = value
+          write_attribute(translations_column, translations)
+        end
+
+        # Predicate method
+        getter_method = attr.to_sym
+        define_method("#{attr}?") do
+          send(getter_method).present?
+        end
+
+        # Raw translations hash accessor
+        define_method("#{attr}_translations") do
+          read_attribute(translations_column)
+        end
+
+        # Set all translations at once
+        define_method("#{attr}_translations=") do |hash|
+          write_attribute(translations_column, hash&.stringify_keys || {})
+        end
+      end
+
+      # Defines locale-specific accessors (title_en, title_de, etc.)
+      def define_locale_accessors(attr)
+        translations_column = "#{attr}_translations"
+
+        Internationalize.locales.each do |locale|
+          locale_str = locale.to_s
+          getter_method = :"#{attr}_#{locale}"
+
+          # Getter: article.title_en
+          define_method(getter_method) do
+            translations = read_attribute(translations_column)
+            translations[locale_str]
+          end
+
+          # Setter: article.title_en = "Hello"
+          define_method("#{attr}_#{locale}=") do |value|
+            translations = read_attribute(translations_column)
+            translations[locale_str] = value
+            write_attribute(translations_column, translations)
+          end
+
+          # Predicate: article.title_en?
+          define_method("#{attr}_#{locale}?") do
+            send(getter_method).present?
+          end
+        end
+      end
+    end
+
+    # Instance methods
+
+    # Set translation for a specific locale
+    def set_translation(attr, locale, value)
+      column = "#{attr}_translations"
+      translations = read_attribute(column)
+      translations[locale.to_s] = value
+      write_attribute(column, translations)
+    end
+
+    # Get translation for a specific locale without fallback
+    def translation_for(attr, locale)
+      translations = read_attribute("#{attr}_translations")
+      translations[locale.to_s]
+    end
+
+    # Check if a translation exists for a specific locale
+    def translated?(attr, locale)
+      translation_for(attr, locale).present?
+    end
+
+    # Returns all locales that have a translation for an attribute
+    def translated_locales(attr)
+      translations = read_attribute("#{attr}_translations")
+      translations.filter_map { |k, v| k.to_sym if v.present? }
+    end
+  end
+end

data/lib/internationalize/version.rb

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

data/lib/internationalize.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_record"
+
+require_relative "internationalize/version"
+require_relative "internationalize/adapters"
+require_relative "internationalize/model"
+
+module Internationalize
+  class << self
+    # Configuration
+    attr_accessor :fallback_locale, :available_locales
+
+    def configure
+      yield self
+    end
+
+    # Returns the current locale, defaulting to I18n.locale
+    def locale
+      I18n.locale
+    end
+
+    # Returns the default locale for fallbacks
+    def default_locale
+      fallback_locale || I18n.default_locale
+    end
+
+    # Returns available locales, defaulting to I18n.available_locales
+    def locales
+      available_locales || I18n.available_locales
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: internationalize
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sampo Kuokkanen
+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: activesupport
+  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: Zero-config internationalization for ActiveRecord models using JSON columns.
+  No JOINs, no N+1 queries, just fast inline translations. Supports SQLite, PostgreSQL,
+  and MySQL.
+email:
+- sampo.kuokkanen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/internationalize/translation/templates/add_translations_migration.rb.erb
+- lib/generators/internationalize/translation_generator.rb
+- lib/internationalize.rb
+- lib/internationalize/adapters.rb
+- lib/internationalize/adapters/base.rb
+- lib/internationalize/adapters/mysql.rb
+- lib/internationalize/adapters/postgresql.rb
+- lib/internationalize/adapters/sqlite.rb
+- lib/internationalize/model.rb
+- lib/internationalize/version.rb
+homepage: https://github.com/sampokuokkanen/internationalize
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sampokuokkanen/internationalize
+  source_code_uri: https://github.com/sampokuokkanen/internationalize
+  changelog_uri: https://github.com/sampokuokkanen/internationalize/blob/main/CHANGELOG.md
+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.7.2
+specification_version: 4
+summary: Lightweight, performant i18n for Rails with JSON column storage
+test_files: []