internationalize 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0808602c10b51ee1884f04c5b9fd66d05381d07c0f86d284517dce7f02ebb6cd'
-  data.tar.gz: fe0c214e9c386b191d4e8f06e1ddee136d9e7a15b25a59d4dd0c9a4860a6589a
+  metadata.gz: e35fc3d32a34b9dde3097192bd791ffb50b8d62a68b1520347da4ed2ac72224f
+  data.tar.gz: decad482b4b5f99fedf070f2f64fb655f088ab6397f709a5362623f59570342d
 SHA512:
-  metadata.gz: 18cf19554d3187476b26505e555e7f181fb6c31edc100e054a2a96f8eafbdb09fa1ad424544973abc349a8f68c62ec0d5634216c6d4fd4cfd029221331d620ed
-  data.tar.gz: d998cbcd3ede8f8a1574e3adcec37ae3afb6216772de801ed0693199bbe70befe398f89a0ff001a66f149cc10f226ed5fd93721c44067e3ebd0ba62ad6e6643d
+  metadata.gz: 2a652e6a3725561e8b5455b6676a490d214aff84f78163b5ab02385a4708381e80cdb8125782b1cb36eab9ae386384768e0231a7e988cf637ddbf464a8ff62d8
+  data.tar.gz: d4e980bb9d34168a802660b918bf3d092cf6b9be3b62d1b81696aa3d9ee5d026dcb335e4993fa6ca55a9b4964d58a82eaefd7d6fbedd8eae64ede2a99391519b

data/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.4.0] - 2025-12-02
+
+### Added
+
+- `i18n_where` query method as a short, convenient alias for querying translated attributes
+  - `Article.i18n_where(title: "Hello")` - exact match
+  - `Article.i18n_where(title: "hello", match: :partial)` - LIKE match
+
+### Deprecated
+
+- Using `international` for querying is now deprecated; use `i18n_where` or `international_where` instead
+  - A deprecation warning is now emitted when using `international` for queries
+
 ## [0.3.0] - 2024-12-01
 
 ### Added
@@ -13,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `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
+- `international_where` query method as a clearer alternative to `international` for queries
 
 ## [0.2.4] - 2024-11-29
 

data/README.md

@@ -119,13 +119,12 @@ All query methods default to the current `I18n.locale` and return ActiveRecord r
 
 ```ruby
 # Exact match on translation (uses current locale by default)
-Article.international(title: "Hello World")
-Article.international(title: "Hallo Welt", locale: :de)
+Article.i18n_where(title: "Hello World")
+Article.i18n_where(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)
+Article.i18n_where(title: "hello", match: :partial)
+Article.i18n_where(title: "Hello", match: :partial, case_sensitive: true)
 
 # Exclude matches
 Article.international_not(title: "Draft")
@@ -142,19 +141,15 @@ Article.translated(:title, locale: :de)
 Article.untranslated(:title, locale: :de)
 
 # Chain with ActiveRecord methods
-Article.international(title: "Hello World")
+Article.i18n_where(title: "Hello World")
        .where(published: true)
        .includes(:author)
        .limit(10)
 
 # Combine queries
-Article.international(title: "hello", match: :partial)
+Article.i18n_where(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
@@ -210,12 +205,50 @@ class Article < ApplicationRecord
 end
 ```
 
-Errors from `validates_international` are added to locale-specific keys:
+Errors from `validates_international` are added to the base attribute name for clean user-facing messages:
 
 ```ruby
-article.errors[:title_en]  # => ["has already been taken"]
+article.errors[:title]  # => ["has already been taken"]
+# Displays as: "Title has already been taken" (not "Title en has already been taken")
+```
+
+#### Locale-Specific Error Messages
+
+For admin interfaces where you need to indicate which specific locale failed validation, use custom validations that add errors to locale-suffixed attributes:
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title
+
+  validate :validate_required_translations
+
+  private
+
+  def validate_required_translations
+    [:en, :de].each do |locale|
+      if send("title_#{locale}").blank?
+        errors.add("title_#{locale}", :blank)
+      end
+    end
+  end
+end
 ```
 
+When using locale-suffixed error keys, configure Rails I18n to provide user-friendly attribute names:
+
+```yaml
+# config/locales/en.yml
+en:
+  activerecord:
+    attributes:
+      article:
+        title_en: "Title (English)"
+        title_de: "Title (German)"
+```
+
+This displays as "Title (German) can't be blank" instead of "Title de can't be blank".
+
 ### ActionText Support
 
 For rich text with attachments (requires ActionText):

data/context/getting-started.md

@@ -71,10 +71,10 @@ article.title_translations  # => {"en" => "Hello World", "de" => "Hallo Welt"}
 
 ```ruby
 # Exact match
-Article.international(title: "Hello World")
+Article.i18n_where(title: "Hello World")
 
 # Partial match (LIKE)
-Article.international(title: "Hello", match: :partial)
+Article.i18n_where(title: "Hello", match: :partial)
 
 # Order by translation
 Article.international_order(:title, :desc)

data/context/model-api.md

@@ -49,17 +49,17 @@ All query methods default to current `I18n.locale` and return `ActiveRecord::Rel
 
 | Method | Description |
 |--------|-------------|
-| `international(**conditions, locale: nil)` | Exact match query |
+| `i18n_where(**conditions, locale: nil, match: :exact)` | Query by translation (short alias) |
+| `international_where(**conditions, locale: nil, match: :exact)` | Query by translation |
 | `international_not(**conditions, locale: nil)` | Exclude matching records |
-| `international_search(**conditions, locale: nil, case_sensitive: false)` | Substring search |
 | `international_order(attr, dir = :asc, locale: nil)` | Order by translation |
 | `translated(*attrs, locale: nil)` | Find records with translation |
 | `untranslated(*attrs, locale: nil)` | Find records missing translation |
 
 ```ruby
 # Examples
-Article.international(title: "Hello World")
-Article.international_search(title: "hello", locale: :de)
+Article.i18n_where(title: "Hello World")
+Article.i18n_where(title: "hello", match: :partial)  # case-insensitive LIKE
 Article.international_order(:title, :desc)
 Article.translated(:title, locale: :de)
 ```
@@ -120,18 +120,45 @@ end
 
 ### Error Keys
 
-Standard Rails validations add errors to the virtual attribute:
+Both standard Rails validations and `validates_international` add errors to the base attribute for clean user-facing messages:
 
 ```ruby
-article.errors[:title]  # => ["can't be blank"]
+article.errors[:title]  # => ["has already been taken"]
+# Displays as: "Title has already been taken" (not "Title en has already been taken")
 ```
 
-`validates_international` adds errors to locale-specific keys:
+#### Locale-Specific Error Messages
+
+For admin interfaces where you need to indicate which specific locale failed, use custom validations that add errors to locale-suffixed attributes:
 
 ```ruby
-article.errors[:title_en]  # => ["has already been taken"]
+validate :validate_required_translations
+
+private
+
+def validate_required_translations
+  [:en, :de].each do |locale|
+    if send("title_#{locale}").blank?
+      errors.add("title_#{locale}", :blank)
+    end
+  end
+end
 ```
 
+When using locale-suffixed error keys, configure Rails I18n for user-friendly display:
+
+```yaml
+# config/locales/en.yml
+en:
+  activerecord:
+    attributes:
+      article:
+        title_en: "Title (English)"
+        title_de: "Title (German)"
+```
+
+This displays as "Title (German) can't be blank" instead of "Title de can't be blank".
+
 ## ActionText Support
 
 For rich text with attachments, include `Internationalize::RichText` and use `international_rich_text`:

data/context/query-api.md

@@ -8,47 +8,40 @@ All query methods default to the current `I18n.locale`. Use the `locale:` option
 
 ```ruby
 # Uses current I18n.locale
-Article.international(title: "Hello World")
+Article.i18n_where(title: "Hello World")
 
 # Explicit locale
-Article.international(title: "Hallo Welt", locale: :de)
+Article.i18n_where(title: "Hallo Welt", locale: :de)
 ```
 
 ## Query Methods
 
-### international(**conditions, locale: nil)
+### i18n_where(**conditions, locale: nil, match: :exact, case_sensitive: false)
 
-Exact match on translated attributes:
+Query by translated attributes. Also available as `international_where`.
+
+Exact match (default):
 
 ```ruby
-Article.international(title: "Hello World")
-Article.international(title: "Hello", status: "published")
-Article.international(title: "Hallo Welt", locale: :de)
+Article.i18n_where(title: "Hello World")
+Article.i18n_where(title: "Hello", status: "published")
+Article.i18n_where(title: "Hallo Welt", locale: :de)
 ```
 
-### international_not(**conditions, locale: nil)
-
-Exclude records matching conditions:
+Partial match (case-insensitive LIKE):
 
 ```ruby
-Article.international_not(title: "Draft")
-Article.international_not(title: "Entwurf", locale: :de)
+Article.i18n_where(title: "hello", match: :partial)
+Article.i18n_where(title: "Hello", match: :partial, case_sensitive: true)
 ```
 
-### international_search(**conditions, locale: nil, case_sensitive: false)
+### international_not(**conditions, locale: nil)
 
-Substring search (LIKE/ILIKE):
+Exclude records matching conditions:
 
 ```ruby
-# Case-insensitive (default)
-Article.international_search(title: "hello")
-Article.international_search(title: "hello", description: "world")
-
-# Case-sensitive
-Article.international_search(title: "Hello", case_sensitive: true)
-
-# With explicit locale
-Article.international_search(title: "welt", locale: :de)
+Article.international_not(title: "Draft")
+Article.international_not(title: "Entwurf", locale: :de)
 ```
 
 ### international_order(attribute, direction = :asc, locale: nil)
@@ -85,7 +78,7 @@ Article.untranslated(:title, locale: :de)
 All methods return `ActiveRecord::Relation`, so they chain naturally with AR methods:
 
 ```ruby
-Article.international(title: "Hello World")
+Article.i18n_where(title: "Hello World")
        .where(published: true)
        .order(created_at: :desc)
        .limit(10)
@@ -98,20 +91,20 @@ Use `merge` to combine multiple international queries:
 
 ```ruby
 # Search + filter + order
-Article.international_search(title: "hello")
-       .merge(Article.international(status: "published"))
+Article.i18n_where(title: "hello", match: :partial)
+       .merge(Article.i18n_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))
+Article.i18n_where(title: "Hello World", locale: :en)
+       .merge(Article.i18n_where(title: "Hallo Welt", locale: :de))
 ```
 
 ## Examples
 
 ```ruby
 # Find published articles with German title containing "Welt"
-Article.international_search(title: "Welt", locale: :de)
+Article.i18n_where(title: "Welt", match: :partial, locale: :de)
        .where(published: true)
        .merge(Article.international_order(:title, locale: :de))
        .limit(10)

data/lib/internationalize/model.rb

@@ -12,8 +12,8 @@ module Internationalize
   #   end
   #
   #   # Querying
-  #   Article.international(title: "Hello")
-  #   Article.international(title: "hello", match: :partial)
+  #   Article.i18n_where(title: "Hello")
+  #   Article.i18n_where(title: "hello", match: :partial)
   #   Article.international_order(:title, :desc)
   #
   module Model
@@ -27,33 +27,57 @@ module Internationalize
     end
 
     class_methods do
-      # Declares attributes as internationalized OR queries by translated attributes
+      # Declares attributes as internationalized
       #
-      # When called with Symbol arguments, declares attributes as internationalized:
+      # @example
       #   international :title, :description
       #
-      # 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 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
+      #
+      # @deprecated Using this method for querying is deprecated.
+      #   Use {#i18n_where} or {#international_where} instead.
       #
       def international(*attributes, 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)
         else
-          # Query mode: Article.international(title: "Hello")
+          # Query mode: Article.international(title: "Hello") - DEPRECATED
+          warn("[Internationalize] DEPRECATION WARNING: Using `international` for querying is deprecated. " \
+            "Use `i18n_where` or `international_where` instead. " \
+            "(called from #{caller(1..1).first})")
           international_query(conditions, locale: locale, match: match, case_sensitive: case_sensitive)
         end
       end
 
+      # Query translated attributes
+      #
+      # @param conditions [Hash] attribute => value pairs to query
+      # @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)
+      # @return [ActiveRecord::Relation]
+      #
+      # @example
+      #   Article.international_where(title: "Hello")
+      #   Article.international_where(title: "hello", match: :partial)
+      #
+      def international_where(locale: nil, match: :exact, case_sensitive: false, **conditions)
+        international_query(conditions, locale: locale, match: match, case_sensitive: case_sensitive)
+      end
+
+      # Short alias for international_where
+      #
+      # @see #international_where
+      #
+      # @example
+      #   Article.i18n_where(title: "Hello")
+      #   Article.i18n_where(title: "hello", match: :partial)
+      #
+      def i18n_where(locale: nil, match: :exact, case_sensitive: false, **conditions)
+        international_query(conditions, locale: locale, match: match, case_sensitive: case_sensitive)
+      end
+
       # Order by translated attribute
       #
       # @param attribute [Symbol] attribute to order by

data/lib/internationalize/validations.rb

@@ -51,7 +51,7 @@ module Internationalize
       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"
+            "For current locale, use: validates :#{attr}, presence: true"
         end
 
         locales = options[:locales].map(&:to_s)
@@ -60,7 +60,7 @@ module Internationalize
           locales.each do |locale|
             value = record.send("#{attr}_#{locale}")
             if value.blank?
-              record.errors.add("#{attr}_#{locale}", :blank)
+              record.errors.add(attr, :blank)
             end
           end
         end
@@ -76,7 +76,7 @@ module Internationalize
           scope = scope.where.not(id: record.id) if record.persisted?
 
           if scope.exists?
-            record.errors.add("#{attr}_#{locale}", :taken)
+            record.errors.add(attr, :taken)
           end
         end
       end

data/lib/internationalize/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internationalize
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sampo Kuokkanen