internationalize 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b22ab7e48ce183d9094dada5300dde85ee7985f3703db4db569f91556507454
-  data.tar.gz: b306eb40ab2635fcf416ce80cd7932b7868dc51a324bfc31b70ae928bc1a72e3
+  metadata.gz: '0808602c10b51ee1884f04c5b9fd66d05381d07c0f86d284517dce7f02ebb6cd'
+  data.tar.gz: fe0c214e9c386b191d4e8f06e1ddee136d9e7a15b25a59d4dd0c9a4860a6589a
 SHA512:
-  metadata.gz: 9e09d4c92ae4d85e65d69d9089146184da9679f82ed3880b5f35c925aeb929853fcadc703771de60e5dccc867160683c71e46ac9db83ca4bd926bb1f936fe5fe
-  data.tar.gz: 81026001e7c16d09a11c9815d37e35757c46c5dd86039ed44bf409a5144ead87e5cb724166d63475323f145b1dcf04df5e27d26e9f01b3cef781b3a38fa788a8
+  metadata.gz: 18cf19554d3187476b26505e555e7f181fb6c31edc100e054a2a96f8eafbdb09fa1ad424544973abc349a8f68c62ec0d5634216c6d4fd4cfd029221331d620ed
+  data.tar.gz: d998cbcd3ede8f8a1574e3adcec37ae3afb6216772de801ed0693199bbe70befe398f89a0ff001a66f149cc10f226ed5fd93721c44067e3ebd0ba62ad6e6643d

data/CHANGELOG.md

@@ -5,7 +5,26 @@ 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).
 
-## [Unreleased]
+## [0.3.0] - 2024-12-01
+
+### Added
+
+- `validates_international` method for locale-specific validations:
+  - `uniqueness: true` - validates uniqueness per-locale (requires JSON column querying)
+  - `presence: { locales: [:en, :de] }` - requires translations for specific locales (useful for admin interfaces)
+- Standard Rails validations (`validates :title, presence: true`) now work with virtual accessors
+
+## [0.2.4] - 2024-11-29
+
+### Added
+
+- Fixtures documentation and tests demonstrating YAML format for translation columns
+
+## [0.2.3] - 2024-11-29
+
+### Added
+
+- Auto-load RichText via Rails Railtie (fixes load order issue)
 
 ## [0.2.2] - 2024-11-29
 

data/README.md

@@ -1,21 +1,27 @@
 # Internationalize
 
+[![Gem Version](https://badge.fury.io/rb/internationalize.svg)](https://rubygems.org/gems/internationalize)
+[![Build](https://github.com/sampokuokkanen/internationalize/workflows/CI/badge.svg)](https://github.com/sampokuokkanen/internationalize/actions)
+
 Lightweight, performant internationalization for Rails with JSON column storage.
 
 ## Why Internationalize?
 
 Internationalize is a focused, lightweight gem that does one thing well: JSON column translations. No backend abstraction layers, no plugin systems, no extra memory overhead.
 
-Unlike Globalize or Mobility which use separate translation tables requiring JOINs, Internationalize stores translations inline using JSON columns. This means:
+Unlike Globalize (separate translation tables) or Mobility (JSON backend is PostgreSQL-only), Internationalize stores translations inline using JSON columns with **full SQLite, PostgreSQL, and MySQL support**:
 
 - **No JOINs** - translations live in the same table
 - **No N+1 queries** - data is always loaded with the record
 - **No backend overhead** - direct JSON column access, no abstraction layers
 - **~50% less memory** - no per-instance backend objects or plugin chains
 - **Direct method dispatch** - no `method_missing` overhead
-- **Multi-database support** - works with SQLite, PostgreSQL, and MySQL
+- **True multi-database JSON support** - SQLite 3.38+, PostgreSQL 9.4+, MySQL 8.0+
+- **ActionText support** - internationalized rich text with attachments
 - **Visible in schema.rb** - translated fields appear directly in your model's schema
 
+> **Note:** Mobility's JSON/JSONB backends only work with PostgreSQL. For SQLite or MySQL, Mobility requires separate translation tables with JOINs. Internationalize provides JSON column querying across all three databases.
+
 ## Supported Databases
 
 | Database | JSON Column | Query Syntax |
@@ -173,9 +179,46 @@ I18n.locale = :de
 article.title  # => "Hello" (falls back to :en)
 ```
 
+### Validations
+
+For most validations, use standard Rails validators—they work with the virtual accessor for the current locale:
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title
+
+  # Standard Rails validations (recommended)
+  validates :title, presence: true
+  validates :title, length: { minimum: 3, maximum: 100 }
+  validates :title, format: { with: /\A[a-z0-9-]+\z/ }
+end
+```
+
+Use `validates_international` only when you need:
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title
+
+  # Uniqueness per-locale (requires JSON column querying)
+  validates_international :title, uniqueness: true
+
+  # Multi-locale presence (for admin interfaces editing all translations at once)
+  validates_international :title, presence: { locales: [:en, :de] }
+end
+```
+
+Errors from `validates_international` are added to locale-specific keys:
+
+```ruby
+article.errors[:title_en]  # => ["has already been taken"]
+```
+
 ### ActionText Support
 
-For rich text with attachments, use `international_rich_text` (auto-loaded when ActionText is available):
+For rich text with attachments (requires ActionText):
 
 ```ruby
 class Article < ApplicationRecord
@@ -196,17 +239,35 @@ article.content.body                  # ActionText::Content object
 article.content.embeds                # Attachments work per-locale
 ```
 
+### Fixtures
+
+Use the `*_translations` column name with nested locale keys:
+
+```yaml
+# test/fixtures/articles.yml
+hello_world:
+  title_translations:
+    en: "Hello World"
+    de: "Hallo Welt"
+  status: published
+```
+
 ## Configuration
 
+No configuration required. Internationalize uses your existing Rails I18n settings:
+
+- **Locales**: `I18n.available_locales`
+- **Fallback**: `I18n.default_locale`
+
+To override locales (rarely needed):
+
 ```ruby
 # config/initializers/internationalize.rb
 Internationalize.configure do |config|
-  config.available_locales = [:en, :de, :fr]  # Defaults to I18n.available_locales
+  config.available_locales = [:en, :de, :fr]
 end
 ```
 
-Fallback uses `I18n.default_locale` automatically.
-
 ## Performance Comparison
 
 Benchmark with 1000 records, 2 translated attributes (title + body), 3 locales:
@@ -237,13 +298,13 @@ Benchmark with 1000 records, 2 translated attributes (title + body), 3 locales:
 
 ### When to consider Mobility
 
-For table-based translation storage, consider [Mobility](https://github.com/shioyama/mobility) instead:
+Consider [Mobility](https://github.com/shioyama/mobility) if:
 
-- 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
+- You need to add translations without modifying existing table schemas
+- You're on PostgreSQL and want their JSON backend (note: PostgreSQL-only)
+- You need the flexibility of multiple backend strategies
 
-Mobility's table backend stores translations in separate tables with JOINs, which trades query performance for schema flexibility.
+Mobility's table backend stores translations in separate tables with JOINs, which trades query performance for schema flexibility. Their JSON backend is PostgreSQL-only.
 
 ## License
 

data/context/configuration.md

@@ -1,17 +1,21 @@
 # Internationalize: Configuration
 
-## Global Configuration
+## Zero Configuration
+
+No configuration required. Internationalize uses your existing Rails I18n settings:
+
+- `I18n.available_locales` - determines which locale accessors are generated
+- `I18n.default_locale` - used for fallback when translation is missing
+
+## Override Locales (Rarely Needed)
 
 ```ruby
 # config/initializers/internationalize.rb
 Internationalize.configure do |config|
-  # Override available locales (defaults to I18n.available_locales)
   config.available_locales = [:en, :de, :fr, :es]
 end
 ```
 
-Fallback locale is always `I18n.default_locale`.
-
 ## Database Setup
 
 Use the generator to create migrations:

data/context/model-api.md

@@ -80,14 +80,66 @@ I18n.locale = :de
 article.title  # => "Hello" (falls back to default locale)
 ```
 
+## Validations
+
+For most validations, use standard Rails validators—they work with the virtual accessor:
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title
+
+  # Standard Rails validations (recommended)
+  validates :title, presence: true
+  validates :title, length: { minimum: 3, maximum: 100 }
+  validates :title, format: { with: /\A[a-z]+\z/ }
+end
+```
+
+Use `validates_international` only for uniqueness or multi-locale presence:
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title
+
+  # Uniqueness per-locale (requires JSON column querying)
+  validates_international :title, uniqueness: true
+
+  # Multi-locale presence (for admin interfaces editing all translations at once)
+  validates_international :title, presence: { locales: [:en, :de] }
+end
+```
+
+### Validation Options
+
+| Option | Description |
+|--------|-------------|
+| `uniqueness: true` | Validates uniqueness per-locale (current locale) |
+| `presence: { locales: [:en, :de] }` | Requires translations for specific locales |
+
+### Error Keys
+
+Standard Rails validations add errors to the virtual attribute:
+
+```ruby
+article.errors[:title]  # => ["can't be blank"]
+```
+
+`validates_international` adds errors to locale-specific keys:
+
+```ruby
+article.errors[:title_en]  # => ["has already been taken"]
+```
+
 ## ActionText Support
 
-For rich text with attachments, use `international_rich_text` (auto-loaded when ActionText is available):
+For rich text with attachments, include `Internationalize::RichText` and use `international_rich_text`:
 
 ```ruby
 class Article < ApplicationRecord
   include Internationalize::Model
-  include Internationalize::RichText
+  include Internationalize::RichText  # Requires ActionText
 
   international_rich_text :content
 end
@@ -113,3 +165,36 @@ article.content                    # Gets for current locale (with fallback)
 article.content.body               # ActionText::Content object
 article.content.embeds             # Attachments work per-locale
 ```
+
+## Fixtures
+
+Use the actual column name (`*_translations`) in fixtures, not the virtual accessor:
+
+### Nested Format
+
+```yaml
+# test/fixtures/articles.yml
+hello_world:
+  title_translations:
+    en: "Hello World"
+    de: "Hallo Welt"
+  description_translations:
+    en: "A greeting"
+    de: "Eine Begrüßung"
+  status: published
+```
+
+### Inline Hash Format
+
+```yaml
+japanese_post:
+  title_translations: { en: "Hello", ja: "こんにちは" }
+  status: published
+```
+
+### Important Notes
+
+- Use `title_translations:` (column name), NOT `title:`
+- Keys can be symbols (`:en`) or strings (`"en"`) - YAML converts them
+- Both nested and inline hash formats work identically
+- Missing locales are simply not set (no error)

data/lib/internationalize/model.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "validations"
+
 module Internationalize
   # Mixin for ActiveRecord models to enable internationalization
   #
@@ -16,6 +18,7 @@ module Internationalize
   #
   module Model
     extend ActiveSupport::Concern
+    include Internationalize::Validations
 
     VALID_DIRECTIONS = ["ASC", "DESC"].freeze
 
@@ -334,7 +337,7 @@ module Internationalize
           hash.each_key do |key|
             unless allowed_locales.include?(key.to_s)
               raise ArgumentError, "Invalid locale '#{key}' for #{attr}_translations. " \
-                "Allowed locales: #{allowed_locales.join(', ')}"
+                "Allowed locales: #{allowed_locales.join(", ")}"
             end
           end
 
@@ -351,7 +354,7 @@ module Internationalize
 
           if locale_str.include?("-")
             raise ArgumentError, "Locale '#{locale}' contains a hyphen which is invalid for Ruby method names. " \
-              "Use underscore format instead: :#{locale_str.tr('-', '_')}"
+              "Use underscore format instead: :#{locale_str.tr("-", "_")}"
           end
 
           getter_method = :"#{attr}_#{locale}"

data/lib/internationalize/rich_text.rb

@@ -31,7 +31,7 @@ module Internationalize
           locale_str = locale.to_s
           if locale_str.include?("-")
             raise ArgumentError, "Locale '#{locale}' contains a hyphen which is invalid for Ruby method names. " \
-              "Use underscore format instead: :#{locale_str.tr('-', '_')}"
+              "Use underscore format instead: :#{locale_str.tr("-", "_")}"
           end
         end
 

data/lib/internationalize/validations.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Internationalize
+  # Validation support for internationalized attributes
+  #
+  # For simple validations (presence, length, format), use standard Rails validations
+  # which work with the virtual accessor for the current locale:
+  #
+  #   validates :title, presence: true
+  #   validates :title, length: { minimum: 3 }
+  #
+  # Use validates_international for:
+  # - Uniqueness (requires JSON column querying)
+  # - Multi-locale presence (admin interfaces editing all translations at once)
+  #
+  # @example Uniqueness per-locale
+  #   validates_international :title, uniqueness: true
+  #
+  # @example Require specific locales (admin/manager interfaces)
+  #   validates_international :title, presence: { locales: [:en, :de] }
+  #
+  module Validations
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Validates internationalized attributes
+      #
+      # @param attrs [Array<Symbol>] attribute names to validate
+      # @param options [Hash] validation options
+      # @option options [Boolean] :uniqueness validate uniqueness per-locale (current locale)
+      # @option options [Hash] :presence with :locales array for multi-locale presence
+      #
+      # @example Uniqueness validation (per-locale)
+      #   validates_international :title, uniqueness: true
+      #
+      # @example Multi-locale presence (for admin interfaces)
+      #   validates_international :title, presence: { locales: [:en, :de] }
+      #
+      def validates_international(*attrs, **options)
+        presence_opts = options.delete(:presence)
+        uniqueness_opts = options.delete(:uniqueness)
+
+        attrs.each do |attr|
+          validate_international_presence(attr, presence_opts) if presence_opts
+          validate_international_uniqueness(attr, uniqueness_opts) if uniqueness_opts
+        end
+      end
+
+      private
+
+      def validate_international_presence(attr, options)
+        unless options.is_a?(Hash) && options[:locales]
+          raise ArgumentError, "validates_international presence requires locales: option. " \
+                               "For current locale, use: validates :#{attr}, presence: true"
+        end
+
+        locales = options[:locales].map(&:to_s)
+
+        validate do |record|
+          locales.each do |locale|
+            value = record.send("#{attr}_#{locale}")
+            if value.blank?
+              record.errors.add("#{attr}_#{locale}", :blank)
+            end
+          end
+        end
+      end
+
+      def validate_international_uniqueness(attr, _options)
+        validate do |record|
+          locale = I18n.locale.to_s
+          value = record.send("#{attr}_#{locale}")
+          next if value.blank?
+
+          scope = record.class.international(attr => value, locale: locale)
+          scope = scope.where.not(id: record.id) if record.persisted?
+
+          if scope.exists?
+            record.errors.add("#{attr}_#{locale}", :taken)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/internationalize/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internationalize
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Sampo Kuokkanen
@@ -64,6 +64,7 @@ files:
 - lib/internationalize/adapters/sqlite.rb
 - lib/internationalize/model.rb
 - lib/internationalize/rich_text.rb
+- lib/internationalize/validations.rb
 - lib/internationalize/version.rb
 homepage: https://github.com/sampokuokkanen/internationalize
 licenses: