eluvia-base 3.37.1 → 3.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f3de7ff3e455a14c86e7c241ac9456ef39ca93ba40c32fd0a8dfb480986b644
-  data.tar.gz: 3ee766edbedf1243cf4036ef90b6e84da1b81585dd9115ed387c802280269850
+  metadata.gz: 691157713c8474d969d76eaee1106d331696a45b9458ee64a563762391e43ed3
+  data.tar.gz: 280074f623f0c865a349edaf49c277875c6eeb28374ab8062b0f2aff5f061d67
 SHA512:
-  metadata.gz: 96a8f3748400de99c05d3bc237f5d598de09c07b7366a60336a38051af342bf61a14bd35a96572a704f36f8395213b1288ebd5dd5b78099979d082a0d8016b6d
-  data.tar.gz: 175ea58ec0bc03a3f7a3271ab5447a2676d892df10eee44825c0effe924fa2b3029ec7c8bfc3ef253247f984847485f42e9f4cf49ef8bee64fac2cb2683532aa
+  metadata.gz: 1e202828e32b3c665d109ec6584c68fe4ff047b46a9af05b3119c68118d692e306ab3deac2534bc46779dcfc3e5a51b5af057e21940f0aea56ee076f6df9c8c9
+  data.tar.gz: 6eff59b834d789c738f7499d14770bc89cd2793d38ac337c2c7baf158b166170c94a38f55e7d4a6cad31cee49ba1937f81c1f9e15a9acd6748d711b8eb02356b

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are 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).
+
+## [3.39.0] — 2026-09-18
+
+### Added
+- This changelog, in the format the ci-toolbox release job expects: on release the unreleased
+  heading is rewritten to the released version and date, and the section becomes the description
+  of the GitLab release.
+- `Eluvia::Base::Config.max_page_limit` — upper bound for the `limit` pagination param on
+  `set_pagination` (default `1000`, `nil` disables the check), overridable per controller via
+  `pagination_max_limit` or per call via the `max_limit:` keyword.
+- `Eluvia::Base::Config.disable_pagination_errors` and the `disable_errors:` keyword on
+  `set_pagination`, to restore the previous silent-fallback behavior for an invalid `limit`
+  instead of raising.
+- `allow_meta_only_limit:` keyword on `set_pagination` to reject `limit=0` like any other invalid
+  value, for resources that don't support a meta-only request.
+- Translations (`lib/eluvia/locales/*.yml`) for all validation error messages raised by this gem
+  (ordering, filtering, fieldset, pagination), in the same languages supported by `habarico`
+  (`cs`, `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ro`, `sk`, `uk`).
+- `Eluvia::PaginationHandler.order_by_param_name` — resolves the `order_by`/`orderBy` query
+  parameter name the same way `set_pagination` does, for callers outside this concern (e.g.
+  request-level validators run in a `before_action` ahead of it) that need to read the same
+  parameter without duplicating the `Config.api_case` check.
+
+### Security
+- **BREAKING:** `set_pagination`'s `limit` param is now capped and validated (HAB-946, from the
+  HAB-894 audit). A non-numeric, negative, or above-`max_page_limit` `limit` is rejected with a
+  `422 Unprocessable Entity` (error detail on the `limit` field) instead of being silently
+  truncated or defaulted. `limit=0` no longer raises `ZeroDivisionError` — it's now accepted as a
+  deliberate meta-only request (see `allow_meta_only_limit:`), mirroring `ListPagination` in
+  `eluvia-base-django`. Only a missing or blank `limit` still falls back to `default_limit`,
+  unchanged.
+- **BREAKING:** `set_pagination`'s `order_by` param is now strictly validated (HAB-915, from the
+  HAB-894 audit). Each `field:direction` entry must have exactly one `:` separator, a non-blank
+  field name, and a lower-case `asc`/`desc` direction; anything else is rejected with a
+  `422 Unprocessable Entity` (format errors on `order_by`, direction errors on
+  `order_by__<field>`) instead of being silently truncated to two segments or defaulted to `asc`.
+  A blank `order_by=` no longer raises `NoMethodError` — it's treated as "not supplied" and falls
+  back to `default_order_by`/`fallback_order_by`.

data/README.md

@@ -82,6 +82,58 @@ class TestRecordsController < ApplicationController
 end
 ```
 
+**BREAKING CHANGE:** the `limit` param is now capped. Requests with a `limit` above the configured ceiling are
+rejected with a `422 Unprocessable Entity` (error detail on the `limit` field) instead of being silently accepted.
+A negative or non-numeric `limit` no longer falls through to Kaminari — it now also raises the same `422`. Only a
+missing or blank `limit` param still falls back to `default_limit`, unchanged. `limit=0` is treated as a deliberate
+meta-only request (see below) rather than an error, mirroring `ListPagination` in eluvia-base-django.
+
+The ceiling defaults to `Eluvia::Base::Config.max_page_limit` (`1000` by default, `nil` disables the check):
+
+```ruby
+Eluvia::Base::Config.max_page_limit = 500
+```
+
+It can be overridden per controller by overriding `pagination_max_limit`, or per call via the `max_limit:` keyword
+(an explicit `max_limit: nil` removes the ceiling for that call only, regardless of `pagination_max_limit`):
+
+```ruby
+class TestRecordsController < ApplicationController
+  def pagination_max_limit
+    50
+  end
+end
+```
+
+```ruby
+before_action -> { set_pagination(default_limit: 20, default_offset: 0, max_limit: 50) }, only: [:index]
+```
+
+To restore the pre-validation behavior (invalid or above-ceiling `limit` silently falls back to `default_limit`
+instead of raising `422`), enable `disable_errors` — globally via `Eluvia::Base::Config.disable_pagination_errors =
+true` (default: `false`), or per call via the `disable_errors:` keyword, which takes precedence over the global
+setting:
+
+```ruby
+before_action -> { set_pagination(default_limit: 20, default_offset: 0, disable_errors: true) }, only: [:index]
+```
+
+`limit=0` is accepted by default as a way to request only pagination metadata without fetching any records — check
+`@limit.zero?` in the action and skip the query:
+
+```ruby
+def index
+  @test_records = @limit.zero? ? TestRecord.none : TestRecord.all.order(@order_by).page(@page).per(@limit).padding(@padding)
+end
+```
+
+Pass `allow_meta_only_limit: false` (e.g. for a search-backed resource, mirroring
+`AnySearchCursorBasedPagination` in eluvia-base-django) to reject `limit=0` like any other invalid value instead:
+
+```ruby
+before_action -> { set_pagination(default_limit: 20, default_offset: 0, allow_meta_only_limit: false) }, only: [:index]
+```
+
 ### 2.3. Params parser
 
 You can use `parse_json_param` helper to parse JSON without predefined structure. In case you know the input JSON
@@ -223,3 +275,30 @@ end
 
 If `upload_key` is present on the assigned `Eluvia::File` but no finalizer is registered, a
 `Eluvia::Errors::StandardError` is raised.
+
+### 2.7. Translations
+
+All validation error messages raised by this gem (ordering, filtering, fieldset and pagination errors) go through
+`I18n.t` with an English `default:`, so the gem works out of the box without any locale setup. In addition,
+`lib/eluvia/locales/*.yml` ships ready-made translations — under the `eluvia.errors.*` key namespace — for the
+same set of languages supported by `habarico`: `cs`, `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ro`,
+`sk`, `uk`. These are appended to `I18n.load_path` automatically when the gem loads; a host application only
+needs to add the relevant locale to its own `I18n.available_locales` and set `I18n.locale` as usual. A host app's
+own `config/locales/*.yml` takes precedence over these if it defines the same key.
+
+## 3. Development
+
+### 3.1. Versioning and releases
+
+The gem version lives in `version.json` and is read at load time by `Eluvia::Base.version`. Releases are
+driven by the `ruby-library` component of the
+[ci-toolbox](https://gitlab.eluvia.dev/gitlab-ci/ci-toolbox) — the release job bumps the version, tags it,
+and the tag pipeline publishes the gem to [geminabox](https://geminabox.eluvia.dev) and to
+[rubygems.org](https://rubygems.org/gems/eluvia-base), and creates a GitLab release.
+
+### 3.2. Changelog
+
+Notable changes go to [CHANGELOG.md](CHANGELOG.md) under the `## [Unreleased]` heading, in the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. The release job rewrites that heading to
+the released version and the release date, and uses the section as the description of the GitLab release —
+so what you write there is what the Releases page shows.

data/lib/eluvia/active_record/filtering.rb

@@ -365,19 +365,29 @@ module Eluvia
           return scope if search_term.blank?
           return scope if filters_model_class.nil?
 
-          fields = filters_model_class.search_fields
-          return scope if fields.empty?
+          search_attrs = filters_model_class.search_attrs
+          return scope if search_attrs.empty?
 
           search_term.split.each do |word|
-            sql_parts = fields.map do |field|
-              col = field.is_a?(Symbol) ? "#{self.table_name}.#{field}" : field.to_s
-              "lower(unaccent(trim(#{col}))) LIKE ('%' || lower(unaccent(trim(?))) || '%')"
+            sql_parts = search_attrs.map do |attr_name|
+              col = attr_name.is_a?(Symbol) ? "#{self.table_name}.#{attr_name}" : attr_name.to_s
+              "lower(#{normalize_search_expression(col)}) LIKE ('%' || lower(#{normalize_search_expression('?')}) || '%')"
             end
-            scope = scope.where(sql_parts.join(' OR '), *([word] * fields.size))
+            scope = scope.where(sql_parts.join(' OR '), *([word] * search_attrs.size))
           end
           scope
         end
 
+        # Wraps a search expression in `trim` and, when enabled via config, `unaccent`.
+        # `unaccent` requires the PostgreSQL `unaccent` extension to be enabled in the database.
+        def normalize_search_expression(expr)
+          if Eluvia::Base::Config.search_use_unaccent
+            "unaccent(trim(#{expr}))"
+          else
+            "trim(#{expr})"
+          end
+        end
+
         def apply_filters_for_filter_attrs(scope, params, parent: nil, current_user: nil)
           return scope unless is_filters_model?(filters_model_class)
           filters_model_class.filter_attrs.each do |attr_spec|

data/lib/eluvia/active_record/filters_model.rb

@@ -12,11 +12,20 @@ module Eluvia
 
       class_methods do
 
-        def search_fields(*fields)
-          if fields.empty?
-            @_search_fields ||= []
+        # Declares (with arguments) or returns (without arguments) the attributes searched by the
+        # generic `search` param. Each attribute is compared with a case-insensitive substring match,
+        # OR-combined across all of them.
+        #
+        # @example
+        #   class User::Filters
+        #     include Eluvia::ActiveRecord::FiltersModel
+        #     search_attrs :first_name, :last_name, :email
+        #   end
+        def search_attrs(*attr_names)
+          if attr_names.empty?
+            @_search_attrs ||= []
           else
-            @_search_fields = fields
+            @_search_attrs = attr_names.flatten
           end
         end
 

data/lib/eluvia/base/config.rb

@@ -33,6 +33,26 @@ module Eluvia
       mattr_accessor :uuid_seed
       @@uuid_seed = '12345678-1234-1234-1234-1234567890ab'
 
+      # Whether the generic `search` param should wrap compared columns in the PostgreSQL `unaccent`
+      # function, making the search insensitive to diacritics. Requires the `unaccent` extension to be
+      # enabled in the database (`enable_extension 'unaccent'`). When false, search is only
+      # case-insensitive. (default: true)
+      mattr_accessor :search_use_unaccent
+      @@search_use_unaccent = true
+
+      # Upper bound for the `limit` pagination param on `set_pagination`. Requests with a
+      # higher `limit` are rejected with 422 instead of being silently truncated. `nil`
+      # disables the check. Mirrors `MAX_PAGE_LIMIT` in eluvia-base-django. (default: 1000)
+      mattr_accessor :max_page_limit
+      @@max_page_limit = 1000
+
+      # Whether an invalid `limit` param (non-numeric, negative, above `max_page_limit`, or zero
+      # without `allow_meta_only_limit:`) on `set_pagination` silently falls back to
+      # `default_limit` instead of being rejected with 422. Mirrors `disable_errors` on
+      # `LimitResolutionMixin` in eluvia-base-django. (default: false)
+      mattr_accessor :disable_pagination_errors
+      @@disable_pagination_errors = false
+
     end
   end
 end

data/lib/eluvia/handlers/pagination_handler.rb

@@ -2,23 +2,104 @@ module Eluvia
   module PaginationHandler
     extend ::ActiveSupport::Concern
 
-    def set_pagination(default_limit: 20, default_offset: 0, default_order_by: 'created_at:asc', fallback_order_by: 'created_at:asc', force_order_by: false)
+    # Resolves the query parameter name carrying the `order_by` input according to the configured
+    # API case. Exposed so callers outside this concern (e.g. request-level validators run in a
+    # `before_action` ahead of `set_pagination`) parse the exact same parameter, instead of
+    # duplicating this ternary and risking it drifting out of sync with `Config.api_case`.
+    def self.order_by_param_name
+      Eluvia::Base::Config.api_case == 'camel_case' ? :orderBy : :order_by
+    end
+
+    # Sentinel distinguishing an unset `max_limit:` kwarg (defer to `pagination_max_limit`) from
+    # an explicit `max_limit: nil` (no ceiling for this call only, regardless of the config/method).
+    NOT_SET = Object.new.freeze
+
+    # Ceiling applied to `limit` for this controller. Override to customize (e.g. a
+    # per-resource value pulled from a resource definition). Defaults to the library-wide config.
+    def pagination_max_limit
+      Eluvia::Base::Config.max_page_limit
+    end
+
+    def set_pagination(default_limit: 20, default_offset: 0, default_order_by: 'created_at:asc',
+                       fallback_order_by: 'created_at:asc', force_order_by: false, max_limit: NOT_SET,
+                       disable_errors: nil, allow_meta_only_limit: true)
 
       # Pagination
-      @limit = params[:limit] ? params[:limit].to_i : default_limit
+      @limit = resolve_pagination_limit(default_limit: default_limit, max_limit: max_limit,
+        disable_errors: disable_errors, allow_meta_only_limit: allow_meta_only_limit)
+
       @offset = params[:offset] ? params[:offset].to_i : default_offset
-      @page = (@offset / @limit) + 1
-      @padding = @offset % @limit
+      if @limit.zero?
+        # Meta-only request (see `allow_meta_only_limit:`) - no records to page through.
+        @page = 1
+        @padding = 0
+      else
+        @page = (@offset / @limit) + 1
+        @padding = @offset % @limit
+      end
 
       # Order by
+      order_by_param = Eluvia::PaginationHandler.order_by_param_name
+      user_order_by = params[order_by_param].to_s.strip
+      # A blank `order_by` is treated as "not supplied" (falls through to defaults/fallback)
+      # rather than as a literal empty ordering, since a Kaminari scope always needs some order.
+      order_by = !force_order_by && user_order_by.present? ? user_order_by : default_order_by
+      order_by = "#{order_by},#{fallback_order_by}"
+
       @order_by = {}
-      order_by_param = Eluvia::Base::Config.api_case == 'camel_case' ? :orderBy : :order_by
-      order_by = "#{!force_order_by && params.key?(order_by_param) ? params[order_by_param] : default_order_by},#{fallback_order_by}"
-      order_by.to_s.split(',').each do |o|
-        s = o.to_s.split(':')
-        @order_by[s.first] = s.length >= 2 && s[1].downcase == 'desc' ? :desc : :asc
+      order_by.split(',').each do |entry|
+        entry = entry.strip
+        # `-1` keeps a trailing empty segment (e.g. `name:`) instead of Ruby's default of
+        # dropping it, so it is caught below as an invalid direction rather than as a bare field.
+        parts = entry.split(':', -1)
+        field_name, direction = parts
+
+        if parts.length != 2 || field_name.blank?
+          raise Eluvia::Errors::UnprocessableEntity.new({
+            'order_by' => I18n.t('eluvia.errors.ordering.invalid_format',
+              default: 'Invalid format, expected "field_name:asc" or "field_name:desc".')
+          })
+        end
+
+        unless %w[asc desc].include?(direction)
+          raise Eluvia::Errors::UnprocessableEntity.new({
+            "order_by__#{field_name}" => I18n.t('eluvia.errors.ordering.invalid_direction',
+              default: 'Invalid order direction. Allowed values are `asc` and `desc`.')
+          })
+        end
+
+        @order_by[field_name] = direction.to_sym
+      end
+
+    end
+
+    private
+
+    def resolve_pagination_limit(default_limit:, max_limit:, disable_errors:, allow_meta_only_limit:)
+      return default_limit unless params[:limit].present?
+
+      raw_limit = params[:limit].to_s
+      parsed_limit = raw_limit.match?(/\A-?\d+\z/) ? raw_limit.to_i : nil
+      errors_disabled = disable_errors.nil? ? Eluvia::Base::Config.disable_pagination_errors : disable_errors
+
+      if parsed_limit.nil? || parsed_limit.negative? || (parsed_limit.zero? && !allow_meta_only_limit)
+        return default_limit if errors_disabled
+
+        msg = I18n.t('eluvia.errors.pagination.invalid_limit',
+          default: 'Limit must be a positive integer, got %<limit>s.', limit: params[:limit])
+        raise Eluvia::Errors::UnprocessableEntity.new('limit' => msg)
+      end
+
+      ceiling = max_limit == NOT_SET ? pagination_max_limit : max_limit
+      if ceiling && parsed_limit > ceiling
+        return default_limit if errors_disabled
+
+        msg = I18n.t('eluvia.errors.pagination.max_limit_exceeded',
+          default: 'Limit %<limit>s exceeds the maximum allowed limit of %<max>s.', limit: parsed_limit, max: ceiling)
+        raise Eluvia::Errors::UnprocessableEntity.new('limit' => msg)
       end
 
+      parsed_limit
     end
 
   end

data/lib/eluvia/locales/cs.yml

@@ -0,0 +1,22 @@
+cs:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Neplatný formát, očekává se "field_name:asc" nebo "field_name:desc".'
+        invalid_direction: "Neplatný směr řazení. Povolené hodnoty jsou `asc` a `desc`."
+        invalid_definition: "Neplatná definice atributu `order by`. Očekává se pouze jeden oddělovač `__`."
+        association_not_found: "Asociace nenalezena."
+        not_found_on_association: "Na asociaci neexistuje."
+        not_found: "Neexistuje."
+      filter:
+        unknown_param: "Neznámý parametr filtru."
+        invalid_term: "Neplatný filtrovací výraz."
+        invalid_value_format: "Neplatný formát hodnoty."
+        invalid_uuid_format: "Neplatný formát UUID."
+        invalid_integer_format: "Neplatný formát celého čísla."
+        invalid_date_format: "Neplatný formát data."
+      fieldset:
+        unknown_field: "Neznámé pole."
+      pagination:
+        invalid_limit: "Limit musí být kladné celé číslo, zadáno %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s překračuje maximální povolený limit %<max>s."

data/lib/eluvia/locales/de.yml

@@ -0,0 +1,22 @@
+de:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Ungültiges Format, erwartet wird "field_name:asc" oder "field_name:desc".'
+        invalid_direction: "Ungültige Sortierrichtung. Erlaubte Werte sind `asc` und `desc`."
+        invalid_definition: "Ungültige Definition für ein `order by`-Attribut. Es wird genau ein `__`-Trennzeichen erwartet."
+        association_not_found: "Assoziation nicht gefunden."
+        not_found_on_association: "Existiert nicht in der Assoziation."
+        not_found: "Existiert nicht."
+      filter:
+        unknown_param: "Unbekannter Filterparameter."
+        invalid_term: "Ungültiger Filterbegriff."
+        invalid_value_format: "Ungültiges Wertformat."
+        invalid_uuid_format: "Ungültiges UUID-Format."
+        invalid_integer_format: "Ungültiges Ganzzahlformat."
+        invalid_date_format: "Ungültiges Datumsformat."
+      fieldset:
+        unknown_field: "Unbekanntes Feld."
+      pagination:
+        invalid_limit: "Limit muss eine positive Ganzzahl sein, erhalten: %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s überschreitet das maximal zulässige Limit von %<max>s."

data/lib/eluvia/locales/en.yml

@@ -0,0 +1,25 @@
+# Translations for the validation error messages raised by eluvia-base (ordering.rb, filtering.rb,
+# fieldset_serializer.rb, pagination_handler.rb). Each key mirrors the `default:` string passed to
+# `I18n.t` at the call site, so a host app without these locale files still gets the same English text.
+en:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Invalid format, expected "field_name:asc" or "field_name:desc".'
+        invalid_direction: "Invalid order direction. Allowed values are `asc` and `desc`."
+        invalid_definition: "Invalid definition for an `order by` attribute. Expecting only one `__` delimiter."
+        association_not_found: "Association not found."
+        not_found_on_association: "Does not exist on association."
+        not_found: "Does not exist."
+      filter:
+        unknown_param: "Unknown filter param."
+        invalid_term: "Invalid filter term."
+        invalid_value_format: "Invalid value format."
+        invalid_uuid_format: "Invalid UUID format."
+        invalid_integer_format: "Invalid integer format."
+        invalid_date_format: "Invalid date format."
+      fieldset:
+        unknown_field: "Unknown field."
+      pagination:
+        invalid_limit: "Limit must be a positive integer, got %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s exceeds the maximum allowed limit of %<max>s."

data/lib/eluvia/locales/es.yml

@@ -0,0 +1,22 @@
+es:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Formato no válido, se espera "field_name:asc" o "field_name:desc".'
+        invalid_direction: "Dirección de ordenación no válida. Los valores permitidos son `asc` y `desc`."
+        invalid_definition: "Definición no válida para un atributo `order by`. Se espera solo un delimitador `__`."
+        association_not_found: "Asociación no encontrada."
+        not_found_on_association: "No existe en la asociación."
+        not_found: "No existe."
+      filter:
+        unknown_param: "Parámetro de filtro desconocido."
+        invalid_term: "Término de filtro no válido."
+        invalid_value_format: "Formato de valor no válido."
+        invalid_uuid_format: "Formato de UUID no válido."
+        invalid_integer_format: "Formato de número entero no válido."
+        invalid_date_format: "Formato de fecha no válido."
+      fieldset:
+        unknown_field: "Campo desconocido."
+      pagination:
+        invalid_limit: "El límite debe ser un número entero positivo, recibido %<limit>s."
+        max_limit_exceeded: "El límite %<limit>s supera el límite máximo permitido de %<max>s."

data/lib/eluvia/locales/fr.yml

@@ -0,0 +1,22 @@
+fr:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Format invalide, attendu "field_name:asc" ou "field_name:desc".'
+        invalid_direction: "Direction de tri invalide. Les valeurs autorisées sont `asc` et `desc`."
+        invalid_definition: "Définition invalide pour un attribut `order by`. Un seul délimiteur `__` est attendu."
+        association_not_found: "Association introuvable."
+        not_found_on_association: "N'existe pas sur l'association."
+        not_found: "N'existe pas."
+      filter:
+        unknown_param: "Paramètre de filtre inconnu."
+        invalid_term: "Terme de filtre invalide."
+        invalid_value_format: "Format de valeur invalide."
+        invalid_uuid_format: "Format UUID invalide."
+        invalid_integer_format: "Format d'entier invalide."
+        invalid_date_format: "Format de date invalide."
+      fieldset:
+        unknown_field: "Champ inconnu."
+      pagination:
+        invalid_limit: "La limite doit être un entier positif, valeur reçue %<limit>s."
+        max_limit_exceeded: "La limite %<limit>s dépasse la limite maximale autorisée de %<max>s."

data/lib/eluvia/locales/it.yml

@@ -0,0 +1,22 @@
+it:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Formato non valido, previsto "field_name:asc" oppure "field_name:desc".'
+        invalid_direction: "Direzione di ordinamento non valida. I valori consentiti sono `asc` e `desc`."
+        invalid_definition: "Definizione non valida per un attributo `order by`. È previsto un solo delimitatore `__`."
+        association_not_found: "Associazione non trovata."
+        not_found_on_association: "Non esiste nell'associazione."
+        not_found: "Non esiste."
+      filter:
+        unknown_param: "Parametro di filtro sconosciuto."
+        invalid_term: "Termine di filtro non valido."
+        invalid_value_format: "Formato del valore non valido."
+        invalid_uuid_format: "Formato UUID non valido."
+        invalid_integer_format: "Formato numero intero non valido."
+        invalid_date_format: "Formato data non valido."
+      fieldset:
+        unknown_field: "Campo sconosciuto."
+      pagination:
+        invalid_limit: "Il limite deve essere un numero intero positivo, ricevuto %<limit>s."
+        max_limit_exceeded: "Il limite %<limit>s supera il limite massimo consentito di %<max>s."

data/lib/eluvia/locales/ja.yml

@@ -0,0 +1,22 @@
+ja:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: '形式が無効です。"field_name:asc" または "field_name:desc" を指定してください。'
+        invalid_direction: "並び順が無効です。使用できる値は `asc` と `desc` です。"
+        invalid_definition: "`order by` 属性の定義が無効です。`__` 区切り文字は1つだけ使用できます。"
+        association_not_found: "アソシエーションが見つかりません。"
+        not_found_on_association: "アソシエーション上に存在しません。"
+        not_found: "存在しません。"
+      filter:
+        unknown_param: "不明なフィルターパラメータです。"
+        invalid_term: "フィルター条件が無効です。"
+        invalid_value_format: "値の形式が無効です。"
+        invalid_uuid_format: "UUID の形式が無効です。"
+        invalid_integer_format: "整数の形式が無効です。"
+        invalid_date_format: "日付の形式が無効です。"
+      fieldset:
+        unknown_field: "不明なフィールドです。"
+      pagination:
+        invalid_limit: "limit は正の整数である必要があります（指定値: %<limit>s）。"
+        max_limit_exceeded: "limit %<limit>s は許可されている最大値 %<max>s を超えています。"

data/lib/eluvia/locales/nl.yml

@@ -0,0 +1,22 @@
+nl:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Ongeldig formaat, verwacht wordt "field_name:asc" of "field_name:desc".'
+        invalid_direction: "Ongeldige sorteerrichting. Toegestane waarden zijn `asc` en `desc`."
+        invalid_definition: "Ongeldige definitie voor een `order by`-attribuut. Er wordt precies één `__`-scheidingsteken verwacht."
+        association_not_found: "Associatie niet gevonden."
+        not_found_on_association: "Bestaat niet binnen de associatie."
+        not_found: "Bestaat niet."
+      filter:
+        unknown_param: "Onbekende filterparameter."
+        invalid_term: "Ongeldige filterterm."
+        invalid_value_format: "Ongeldig waardeformaat."
+        invalid_uuid_format: "Ongeldig UUID-formaat."
+        invalid_integer_format: "Ongeldig geheel-getalformaat."
+        invalid_date_format: "Ongeldig datumformaat."
+      fieldset:
+        unknown_field: "Onbekend veld."
+      pagination:
+        invalid_limit: "Limit moet een positief geheel getal zijn, ontvangen: %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s overschrijdt de maximaal toegestane limiet van %<max>s."

data/lib/eluvia/locales/pl.yml

@@ -0,0 +1,22 @@
+pl:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Nieprawidłowy format, oczekiwano "field_name:asc" lub "field_name:desc".'
+        invalid_direction: "Nieprawidłowy kierunek sortowania. Dozwolone wartości to `asc` i `desc`."
+        invalid_definition: "Nieprawidłowa definicja atrybutu `order by`. Oczekiwany jest dokładnie jeden separator `__`."
+        association_not_found: "Nie znaleziono powiązania."
+        not_found_on_association: "Nie istnieje w powiązaniu."
+        not_found: "Nie istnieje."
+      filter:
+        unknown_param: "Nieznany parametr filtra."
+        invalid_term: "Nieprawidłowy termin filtra."
+        invalid_value_format: "Nieprawidłowy format wartości."
+        invalid_uuid_format: "Nieprawidłowy format UUID."
+        invalid_integer_format: "Nieprawidłowy format liczby całkowitej."
+        invalid_date_format: "Nieprawidłowy format daty."
+      fieldset:
+        unknown_field: "Nieznane pole."
+      pagination:
+        invalid_limit: "Limit musi być dodatnią liczbą całkowitą, otrzymano %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s przekracza maksymalny dozwolony limit %<max>s."

data/lib/eluvia/locales/pt.yml

@@ -0,0 +1,22 @@
+pt:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Formato inválido, esperado "field_name:asc" ou "field_name:desc".'
+        invalid_direction: "Direção de ordenação inválida. Os valores permitidos são `asc` e `desc`."
+        invalid_definition: "Definição inválida para o atributo `order by`. É esperado apenas um delimitador `__`."
+        association_not_found: "Associação não encontrada."
+        not_found_on_association: "Não existe na associação."
+        not_found: "Não existe."
+      filter:
+        unknown_param: "Parâmetro de filtro desconhecido."
+        invalid_term: "Termo de filtro inválido."
+        invalid_value_format: "Formato de valor inválido."
+        invalid_uuid_format: "Formato de UUID inválido."
+        invalid_integer_format: "Formato de número inteiro inválido."
+        invalid_date_format: "Formato de data inválido."
+      fieldset:
+        unknown_field: "Campo desconhecido."
+      pagination:
+        invalid_limit: "O limite deve ser um número inteiro positivo, recebido %<limit>s."
+        max_limit_exceeded: "O limite %<limit>s excede o limite máximo permitido de %<max>s."

data/lib/eluvia/locales/ro.yml

@@ -0,0 +1,22 @@
+ro:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Format invalid, se așteaptă "field_name:asc" sau "field_name:desc".'
+        invalid_direction: "Direcție de sortare invalidă. Valorile permise sunt `asc` și `desc`."
+        invalid_definition: "Definiție invalidă pentru atributul `order by`. Este permis un singur delimitator `__`."
+        association_not_found: "Asocierea nu a fost găsită."
+        not_found_on_association: "Nu există în asociere."
+        not_found: "Nu există."
+      filter:
+        unknown_param: "Parametru de filtrare necunoscut."
+        invalid_term: "Termen de filtrare invalid."
+        invalid_value_format: "Format de valoare invalid."
+        invalid_uuid_format: "Format UUID invalid."
+        invalid_integer_format: "Format de număr întreg invalid."
+        invalid_date_format: "Format de dată invalid."
+      fieldset:
+        unknown_field: "Câmp necunoscut."
+      pagination:
+        invalid_limit: "Limita trebuie să fie un număr întreg pozitiv, valoare primită %<limit>s."
+        max_limit_exceeded: "Limita %<limit>s depășește limita maximă permisă de %<max>s."

data/lib/eluvia/locales/sk.yml

@@ -0,0 +1,22 @@
+sk:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Neplatný formát, očakáva sa "field_name:asc" alebo "field_name:desc".'
+        invalid_direction: "Neplatný smer radenia. Povolené hodnoty sú `asc` a `desc`."
+        invalid_definition: "Neplatná definícia atribútu `order by`. Očakáva sa iba jeden oddeľovač `__`."
+        association_not_found: "Asociácia nebola nájdená."
+        not_found_on_association: "Na asociácii neexistuje."
+        not_found: "Neexistuje."
+      filter:
+        unknown_param: "Neznámy parameter filtra."
+        invalid_term: "Neplatný filtrovací výraz."
+        invalid_value_format: "Neplatný formát hodnoty."
+        invalid_uuid_format: "Neplatný formát UUID."
+        invalid_integer_format: "Neplatný formát celého čísla."
+        invalid_date_format: "Neplatný formát dátumu."
+      fieldset:
+        unknown_field: "Neznáme pole."
+      pagination:
+        invalid_limit: "Limit musí byť kladné celé číslo, zadané %<limit>s."
+        max_limit_exceeded: "Limit %<limit>s prekračuje maximálny povolený limit %<max>s."

data/lib/eluvia/locales/uk.yml

@@ -0,0 +1,22 @@
+uk:
+  eluvia:
+    errors:
+      ordering:
+        invalid_format: 'Недійсний формат, очікується "field_name:asc" або "field_name:desc".'
+        invalid_direction: "Недійсний напрямок сортування. Дозволені значення: `asc` і `desc`."
+        invalid_definition: "Недійсне визначення атрибута `order by`. Очікується рівно один роздільник `__`."
+        association_not_found: "Асоціацію не знайдено."
+        not_found_on_association: "Не існує в асоціації."
+        not_found: "Не існує."
+      filter:
+        unknown_param: "Невідомий параметр фільтра."
+        invalid_term: "Недійсний термін фільтра."
+        invalid_value_format: "Недійсний формат значення."
+        invalid_uuid_format: "Недійсний формат UUID."
+        invalid_integer_format: "Недійсний формат цілого числа."
+        invalid_date_format: "Недійсний формат дати."
+      fieldset:
+        unknown_field: "Невідоме поле."
+      pagination:
+        invalid_limit: "Ліміт має бути додатним цілим числом, отримано %<limit>s."
+        max_limit_exceeded: "Ліміт %<limit>s перевищує максимально допустимий ліміт %<max>s."

data/lib/eluvia-base.rb

@@ -4,6 +4,9 @@ require 'eluvia/base/config'
 # Version
 require 'eluvia/base/version'
 
+# Locales (translations for the validation error messages raised across this gem)
+I18n.load_path += Dir[File.expand_path('eluvia/locales/*.yml', __dir__)]
+
 # Uploads
 require 'eluvia/uploads'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eluvia-base
 version: !ruby/object:Gem::Version
-  version: 3.37.1
+  version: 3.39.0
 platform: ruby
 authors:
 - Matěj Outlý
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -117,6 +117,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/eluvia-base.rb
@@ -149,6 +150,19 @@ files:
 - lib/eluvia/handlers/params_handler.rb
 - lib/eluvia/helpers/attachment_helper.rb
 - lib/eluvia/integrations/eluvia_integration.rb
+- lib/eluvia/locales/cs.yml
+- lib/eluvia/locales/de.yml
+- lib/eluvia/locales/en.yml
+- lib/eluvia/locales/es.yml
+- lib/eluvia/locales/fr.yml
+- lib/eluvia/locales/it.yml
+- lib/eluvia/locales/ja.yml
+- lib/eluvia/locales/nl.yml
+- lib/eluvia/locales/pl.yml
+- lib/eluvia/locales/pt.yml
+- lib/eluvia/locales/ro.yml
+- lib/eluvia/locales/sk.yml
+- lib/eluvia/locales/uk.yml
 - lib/eluvia/models/file.rb
 - lib/eluvia/models/file_wrapper.rb
 - lib/eluvia/models/image_wrapper.rb