internationalize 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0808602c10b51ee1884f04c5b9fd66d05381d07c0f86d284517dce7f02ebb6cd'
-  data.tar.gz: fe0c214e9c386b191d4e8f06e1ddee136d9e7a15b25a59d4dd0c9a4860a6589a
+  metadata.gz: 0a7c08fb66904ff4e73e13f590f4546af940ce8f9adc59d870adf60e71f54fc0
+  data.tar.gz: e6e5b34d18588fc2b8d1fd18b182d73f39bffe2ad67c7f383976eaa30d8b6ee2
 SHA512:
-  metadata.gz: 18cf19554d3187476b26505e555e7f181fb6c31edc100e054a2a96f8eafbdb09fa1ad424544973abc349a8f68c62ec0d5634216c6d4fd4cfd029221331d620ed
-  data.tar.gz: d998cbcd3ede8f8a1574e3adcec37ae3afb6216772de801ed0693199bbe70befe398f89a0ff001a66f149cc10f226ed5fd93721c44067e3ebd0ba62ad6e6643d
+  metadata.gz: 6bf2d4d4e0cfcb36adbd787f3a839dd6bbe4290468eb2934b99af4c4541d948aef7d3f5ea71329e2f99aabe1f2530c83af8955d544d8991e0a9341b4abd393cb
+  data.tar.gz: 5ccafbadb398e1ad9b956990b10334c80577f248d32b4e788a94dc5ad39fffdb47fa1c22eb892216af71784ea4770b4d0bfac43ceeaac951cff63575a4ce1152

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

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)
 ```

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)

data/lib/internationalize/version.rb

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

metadata

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