haveapi 0.28.3 → 0.29.0

data/lib/haveapi/metadata.rb

@@ -45,12 +45,34 @@ module HaveAPI
         end
       end
 
-      def describe(context)
+      def describe(context, type:)
         {
-          input: @input && @input.describe(context),
-          output: @output && @output.describe(context, metadata: true)
+          input: @input && @input.describe(
+            context,
+            i18n_path: Params.metadata_i18n_path(context, type, :input)
+          ),
+          output: @output && @output.describe(
+            context,
+            metadata: true,
+            i18n_path: Params.metadata_i18n_path(context, type, :output)
+          )
         }
       end
+
+      def parameter_metadata_i18n_items(context, type:)
+        [
+          *@input&.parameter_metadata_i18n_items(
+            context,
+            i18n_path: Params.metadata_i18n_path(context, type, :input),
+            meta_type: type
+          ),
+          *@output&.parameter_metadata_i18n_items(
+            context,
+            i18n_path: Params.metadata_i18n_path(context, type, :output),
+            meta_type: type
+          )
+        ].compact
+      end
     end
   end
 end

data/lib/haveapi/model_adapters/active_record.rb

@@ -81,7 +81,10 @@ module HaveAPI::ModelAdapters
 
           if limit && limit > HaveAPI::Actions::Paginable::MAX_LIMIT
             error!(
-              "limit has to be maximally #{HaveAPI::Actions::Paginable::MAX_LIMIT}",
+              HaveAPI.message(
+                'haveapi.pagination.limit_max',
+                max: HaveAPI::Actions::Paginable::MAX_LIMIT
+              ),
               {},
               http_status: 400
             )
@@ -174,18 +177,18 @@ module HaveAPI::ModelAdapters
         if raw.nil?
           return nil if allow_null
 
-          raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+          raise invalid_id(original)
         end
 
         if raw.is_a?(Array) || raw.is_a?(Hash) || [true, false].include?(raw)
-          raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+          raise invalid_id(original)
         elsif raw.is_a?(String)
           stripped = raw.strip
 
           if stripped.empty?
             return nil if allow_null
 
-            raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+            raise invalid_id(original)
           end
 
           raw = stripped
@@ -193,7 +196,7 @@ module HaveAPI::ModelAdapters
 
         value = if integer_pk?(model)
                   id = coerce_integer_id(raw, original)
-                  raise HaveAPI::ValidationError, "not a valid id #{original.inspect}" if id < 0
+                  raise invalid_id(original) if id < 0
 
                   id
                 else
@@ -207,14 +210,14 @@ module HaveAPI::ModelAdapters
               end
 
         if ret.nil? && !allow_null
-          raise HaveAPI::ValidationError, 'resource not found'
+          raise resource_not_found
         end
 
         ret
       rescue ::ActiveRecord::RecordNotFound
-        raise HaveAPI::ValidationError, 'resource not found'
+        raise resource_not_found
       rescue ArgumentError, TypeError
-        raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+        raise invalid_id(original)
       end
 
       def self.integer_pk?(model)
@@ -232,7 +235,7 @@ module HaveAPI::ModelAdapters
           raw
         when Float
           unless raw.finite? && (raw % 1) == 0
-            raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+            raise invalid_id(original)
           end
 
           raw.to_i
@@ -240,23 +243,38 @@ module HaveAPI::ModelAdapters
           s = raw.strip
 
           if s.empty? || !s.match?(/\A[+-]?\d+\z/)
-            raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+            raise invalid_id(original)
           end
 
           Integer(s, 10)
         else
-          raise HaveAPI::ValidationError, "not a valid id #{original.inspect}"
+          raise invalid_id(original)
         end
       end
+
+      def self.invalid_id(original)
+        HaveAPI::ValidationError.new(
+          HaveAPI.message('haveapi.validation.invalid_id', value: original.inspect)
+        )
+      end
+
+      def self.resource_not_found
+        HaveAPI::ValidationError.new(
+          HaveAPI.message('haveapi.validation.resource_not_found')
+        )
+      end
     end
 
     class Output < ::HaveAPI::ModelAdapter::Output
       def self.used_by(action)
         action.meta(:object) do
           output do
-            custom :path_params, label: 'URL parameters',
-                                 desc: 'An array of parameters needed to resolve URL to this object'
-            bool :resolved, label: 'Resolved', desc: 'True if the association is resolved'
+            custom :path_params,
+                   label: HaveAPI.message('haveapi.parameters.active_record.path_params.label'),
+                   desc: HaveAPI.message('haveapi.parameters.active_record.path_params.description')
+            bool :resolved,
+                 label: HaveAPI.message('haveapi.parameters.active_record.resolved.label'),
+                 desc: HaveAPI.message('haveapi.parameters.active_record.resolved.description')
           end
         end
 
@@ -268,30 +286,26 @@ module HaveAPI::ModelAdapters
                    elsif raw.is_a?(Array)
                      raw
                    else
-                     raise HaveAPI::ValidationError, 'includes must be a string or array'
+                     raise HaveAPI::ValidationError,
+                           HaveAPI.message('haveapi.validation.includes_string_or_array')
                    end
 
           values.map do |value|
             unless value.is_a?(String)
-              raise HaveAPI::ValidationError, 'includes must contain only strings'
+              raise HaveAPI::ValidationError,
+                    HaveAPI.message('haveapi.validation.includes_only_strings')
             end
 
             value.strip
           end
         end
 
-        desc = <<~END
-          A list of names of associated resources separated by a comma.
-          Nested associations are declared with '__' between resource names.
-          For example, 'user,node' will resolve the two associations.
-          To resolve further associations of node, use e.g. 'user,node__location',
-          to go even deeper, use e.g. 'user,node__location__environment'.
-        END
-
         action.meta(:global) do
           input do
-            custom :includes, label: 'Included associations',
-                              desc:, &clean
+            custom :includes,
+                   label: HaveAPI.message('haveapi.parameters.active_record.includes.label'),
+                   desc: HaveAPI.message('haveapi.parameters.active_record.includes.description'),
+                   &clean
           end
         end
 

data/lib/haveapi/output_formatter.rb

@@ -51,8 +51,8 @@ module HaveAPI
       ret.update({
         status:,
         response:,
-        message:,
-        errors:
+        message: HaveAPI.localize(message),
+        errors: HaveAPI.localize(errors)
       })
       ret
     end

data/lib/haveapi/parameters/metadata_i18n.rb

@@ -0,0 +1,179 @@
+module HaveAPI::Parameters
+  module MetadataI18n
+    def metadata_i18n_catalog_items(context, i18n_path)
+      %i[label description].filter_map do |kind|
+        fallback = metadata_i18n_fallback(kind)
+        keys = metadata_i18n_keys(context, i18n_path, kind, fallback)
+        value = HaveAPI.localize(fallback).to_s.strip
+
+        next if keys.empty? || value.empty?
+
+        {
+          param: HaveAPI::Params.i18n_segment(@name),
+          kind: metadata_i18n_key_suffix(kind),
+          keys:,
+          value:
+        }
+      end
+    end
+
+    private
+
+    def localized_label(context, i18n_path)
+      localized_metadata(context, i18n_path, :label, @label)
+    end
+
+    def localized_description(context, i18n_path)
+      localized_metadata(context, i18n_path, :description, @desc)
+    end
+
+    def localized_metadata(context, i18n_path, kind, fallback)
+      keys = metadata_i18n_keys(context, i18n_path, kind, fallback)
+      default = HaveAPI.localize(fallback)
+
+      return default if keys.empty?
+
+      keys.each do |key|
+        value = ::I18n.t(key, default: nil)
+        return value unless value.nil?
+      end
+
+      default
+    end
+
+    def metadata_i18n_keys(context, i18n_path, kind, fallback)
+      explicit_key = explicit_metadata_i18n_key(kind)
+
+      return [normalize_metadata_i18n_key(context, explicit_key)] if explicit_key
+      return [] if fallback.is_a?(HaveAPI::LocalizedMessage)
+      return [] unless i18n_path
+
+      scope = parameter_i18n_scope(context)
+      return [] unless scope
+
+      exact_key = [
+        scope,
+        i18n_path,
+        HaveAPI::Params.i18n_segment(@name),
+        metadata_i18n_key_suffix(kind)
+      ].join('.')
+
+      [exact_key, *metadata_i18n_default_keys(context, i18n_path, kind, scope)].uniq
+    end
+
+    def metadata_i18n_fallback(kind)
+      case kind
+      when :label
+        @label
+      when :description
+        @desc
+      else
+        raise ArgumentError, "unsupported parameter metadata kind #{kind.inspect}"
+      end
+    end
+
+    def explicit_metadata_i18n_key(kind)
+      case kind
+      when :label
+        @label_key
+      when :description
+        @desc_key
+      else
+        raise ArgumentError, "unsupported parameter metadata kind #{kind.inspect}"
+      end
+    end
+
+    def normalize_metadata_i18n_key(context, key)
+      str = key.to_s
+      return str if str.include?('.')
+
+      scope = parameter_i18n_scope(context)
+      scope ? "#{scope}.#{str}" : str
+    end
+
+    def parameter_i18n_scope(context)
+      return unless context.respond_to?(:server)
+      return unless context.server.respond_to?(:parameter_i18n_scope)
+
+      scope = context.server.parameter_i18n_scope
+      return if scope.nil? || scope == false
+
+      Array(scope).flat_map { |segment| segment.to_s.split('.') }
+                  .map { |segment| HaveAPI::Params.i18n_segment(segment) }
+                  .join('.')
+    end
+
+    def metadata_i18n_key_suffix(kind)
+      kind == :description ? 'description' : kind.to_s
+    end
+
+    def metadata_i18n_default_keys(context, i18n_path, kind, scope)
+      param = HaveAPI::Params.i18n_segment(@name)
+      suffix = metadata_i18n_key_suffix(kind)
+      resource_prefix = metadata_i18n_resource_prefix(context)
+      path = metadata_i18n_path_parts(i18n_path)
+      keys = []
+
+      if path[:meta_type]
+        if resource_prefix
+          keys << [
+            scope,
+            resource_prefix,
+            'meta',
+            path.fetch(:meta_type),
+            path.fetch(:direction),
+            param,
+            suffix
+          ].join('.')
+        end
+
+        keys << [
+          scope,
+          'meta',
+          path.fetch(:meta_type),
+          path.fetch(:direction),
+          param,
+          suffix
+        ].join('.')
+      elsif resource_prefix
+        keys << [
+          scope,
+          resource_prefix,
+          path.fetch(:direction),
+          param,
+          suffix
+        ].join('.')
+        keys << [
+          scope,
+          resource_prefix,
+          'attributes',
+          param,
+          suffix
+        ].join('.')
+      end
+
+      keys << [scope, 'attributes', param, suffix].join('.') unless path[:meta_type]
+      keys
+    end
+
+    def metadata_i18n_resource_prefix(context)
+      return unless context.respond_to?(:resource_path) && context.resource_path
+
+      [
+        'resources',
+        *context.resource_path.map { |segment| HaveAPI::Params.i18n_segment(segment) }
+      ].join('.')
+    end
+
+    def metadata_i18n_path_parts(i18n_path)
+      parts = i18n_path.to_s.split('.')
+
+      return { direction: parts.last } unless parts[-3] == 'meta'
+
+      {
+        meta_type: parts[-2],
+        direction: parts[-1]
+      }
+    end
+  end
+end

data/lib/haveapi/parameters/resource.rb

@@ -1,16 +1,23 @@
+require_relative 'metadata_i18n'
+
 module HaveAPI::Parameters
   class Resource
+    include MetadataI18n
+
     attr_reader :name, :resource, :label, :desc, :type, :value_id, :value_label,
                 :choices, :value_params
 
     def initialize(resource, name: nil, label: nil, desc: nil,
                    choices: nil, value_id: :id, value_label: :label, required: nil,
-                   db_name: nil, fetch: nil, nullable: nil)
+                   db_name: nil, fetch: nil, nullable: nil, label_key: nil,
+                   desc_key: nil)
       @resource = resource
       @resource_path = build_resource_path(resource)
       @name = name || resource.resource_name.underscore.to_sym
       @label = label || (name && name.to_s.capitalize) || resource.resource_name
       @desc = desc
+      @label_key = label_key
+      @desc_key = desc_key
       @choices = choices || @resource::Index
       @value_id = value_id
       @value_label = value_label
@@ -46,7 +53,7 @@ module HaveAPI::Parameters
       @resource::Index
     end
 
-    def describe(context)
+    def describe(context, i18n_path: nil)
       val_path = context.path_for(
         @resource::Show,
         context.endpoint && context.action_prepare && context.layout == :object && context.call_path_params(context.action, context.action_prepare)
@@ -62,8 +69,8 @@ module HaveAPI::Parameters
       {
         required: required?,
         nullable: nullable?,
-        label: @label,
-        description: @desc,
+        label: localized_label(context, i18n_path),
+        description: localized_description(context, i18n_path),
         type: 'Resource',
         resource: @resource_path,
         value_id: @value_id,
@@ -101,7 +108,7 @@ module HaveAPI::Parameters
       if raw.nil?
         return nil if nullable?
 
-        raise HaveAPI::ValidationError, 'cannot be null'
+        raise validation_error('haveapi.validation.cannot_be_null')
       end
 
       if raw.is_a?(String)
@@ -133,7 +140,7 @@ module HaveAPI::Parameters
     def strip_string(value)
       value.strip
     rescue ArgumentError, Encoding::CompatibilityError
-      raise HaveAPI::ValidationError, 'invalid string encoding'
+      raise validation_error('haveapi.validation.invalid_string_encoding')
     end
 
     def build_resource_path(r)
@@ -175,7 +182,11 @@ module HaveAPI::Parameters
       action = show_action.new(context.request, context.version, path_params, {}, child_context)
       return if action.authorized?(context.current_user)
 
-      raise HaveAPI::ValidationError, 'resource not found'
+      raise validation_error('haveapi.validation.resource_not_found')
+    end
+
+    def validation_error(key, **values)
+      HaveAPI::ValidationError.new(HaveAPI.message(key, **values))
     end
   end
 end

data/lib/haveapi/parameters/typed.rb

@@ -1,11 +1,14 @@
 require 'date'
 require 'time'
+require_relative 'metadata_i18n'
 
 module HaveAPI::Parameters
   class Typed
+    include MetadataI18n
+
     ATTRIBUTES = %i[
       label desc type db_name default fill clean protected load_validators
-      nullable symbolize_keys
+      nullable symbolize_keys label_key desc_key
     ].freeze
 
     attr_reader :name, :label, :desc, :type, :default
@@ -52,12 +55,12 @@ module HaveAPI::Parameters
       @load_validators.nil? || @load_validators
     end
 
-    def describe(context)
+    def describe(context, i18n_path: nil)
       {
         required: required?,
         nullable: nullable?,
-        label: @label,
-        description: @desc,
+        label: localized_label(context, i18n_path),
+        description: localized_description(context, i18n_path),
         type: @type ? @type.to_s : String.to_s,
         validators: @validators ? @validators.describe : {},
         default: @default,
@@ -88,7 +91,7 @@ module HaveAPI::Parameters
       if raw.nil?
         return nil if nullable?
 
-        raise HaveAPI::ValidationError, 'cannot be null'
+        raise validation_error('haveapi.validation.cannot_be_null')
       end
 
       if raw.is_a?(String)
@@ -154,7 +157,7 @@ module HaveAPI::Parameters
 
     def validate_cleaned_value(value)
       if value.nil? && !nullable?
-        raise HaveAPI::ValidationError, 'cannot be null'
+        raise validation_error('haveapi.validation.cannot_be_null')
       end
 
       value
@@ -188,7 +191,7 @@ module HaveAPI::Parameters
     def strip_string(value)
       value.strip
     rescue ArgumentError, Encoding::CompatibilityError
-      raise HaveAPI::ValidationError, 'invalid string encoding'
+      raise validation_error('haveapi.validation.invalid_string_encoding')
     end
 
     def coerce_integer(raw)
@@ -197,7 +200,7 @@ module HaveAPI::Parameters
         raw
       when Float
         unless raw.finite? && (raw % 1) == 0
-          raise HaveAPI::ValidationError, "not a valid integer #{raw.inspect}"
+          raise validation_error('haveapi.types.invalid_integer', value: raw.inspect)
         end
 
         raw.to_i
@@ -205,12 +208,12 @@ module HaveAPI::Parameters
         s = strip_string(raw)
 
         if s.empty? || !s.match?(/\A[+-]?\d+\z/)
-          raise HaveAPI::ValidationError, "not a valid integer #{raw.inspect}"
+          raise validation_error('haveapi.types.invalid_integer', value: raw.inspect)
         end
 
         Integer(s, 10)
       else
-        raise HaveAPI::ValidationError, "not a valid integer #{raw.inspect}"
+        raise validation_error('haveapi.types.invalid_integer', value: raw.inspect)
       end
     end
 
@@ -220,19 +223,19 @@ module HaveAPI::Parameters
 
       elsif raw.is_a?(String)
         s = strip_string(raw)
-        raise HaveAPI::ValidationError, "not a valid float #{raw.inspect}" if s.empty?
+        raise validation_error('haveapi.types.invalid_float', value: raw.inspect) if s.empty?
 
         begin
           f = Float(s)
         rescue ArgumentError
-          raise HaveAPI::ValidationError, "not a valid float #{raw.inspect}"
+          raise validation_error('haveapi.types.invalid_float', value: raw.inspect)
         end
 
       else
-        raise HaveAPI::ValidationError, "not a valid float #{raw.inspect}"
+        raise validation_error('haveapi.types.invalid_float', value: raw.inspect)
       end
 
-      raise HaveAPI::ValidationError, "not a valid float #{raw.inspect}" unless f.finite?
+      raise validation_error('haveapi.types.invalid_float', value: raw.inspect) unless f.finite?
 
       f
     end
@@ -247,35 +250,39 @@ module HaveAPI::Parameters
 
       elsif raw.is_a?(String)
         s = strip_string(raw)
-        raise HaveAPI::ValidationError, "not a valid boolean #{raw.inspect}" if s.empty?
+        raise validation_error('haveapi.types.invalid_boolean', value: raw.inspect) if s.empty?
 
         return true if %w[true t yes y 1].include?(s.downcase)
         return false if %w[false f no n 0].include?(s.downcase)
       end
 
-      raise HaveAPI::ValidationError, "not a valid boolean #{raw.inspect}"
+      raise validation_error('haveapi.types.invalid_boolean', value: raw.inspect)
     end
 
     def coerce_datetime(raw)
       unless raw.is_a?(String)
-        raise HaveAPI::ValidationError, "not in ISO 8601 format '#{raw}'"
+        raise validation_error('haveapi.types.invalid_datetime', value: raw)
       end
 
       if strip_string(raw).empty?
-        raise HaveAPI::ValidationError, "not in ISO 8601 format '#{raw}'"
+        raise validation_error('haveapi.types.invalid_datetime', value: raw)
       end
 
       DateTime.iso8601(raw).to_time
     rescue ArgumentError, TypeError
-      raise HaveAPI::ValidationError, "not in ISO 8601 format '#{raw}'"
+      raise validation_error('haveapi.types.invalid_datetime', value: raw)
     end
 
     def coerce_string(raw)
       if raw.is_a?(Array) || raw.is_a?(Hash)
-        raise HaveAPI::ValidationError, "not a valid string #{raw.inspect}"
+        raise validation_error('haveapi.types.invalid_string', value: raw.inspect)
       end
 
       raw.to_s
     end
+
+    def validation_error(key, **values)
+      HaveAPI::ValidationError.new(HaveAPI.message(key, **values))
+    end
   end
 end