haveapi 0.28.4 → 0.29.0

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

data/lib/haveapi/params.rb

@@ -3,11 +3,22 @@ module HaveAPI
   end
 
   class ValidationError < StandardError
+    attr_reader :message_value
+
     def initialize(msg, errors = {})
+      @message_value = msg
       super(msg)
       @errors = errors
     end
 
+    def message
+      HaveAPI.localize(@message_value)
+    end
+
+    def to_s
+      message
+    end
+
     def to_hash
       @errors
     end
@@ -17,6 +28,45 @@ module HaveAPI
     attr_reader :params
     attr_accessor :action
 
+    class << self
+      def action_i18n_path(context, direction)
+        prefix = action_i18n_prefix(context)
+        return unless prefix
+
+        "#{prefix}.#{i18n_segment(direction)}"
+      end
+
+      def metadata_i18n_path(context, type, direction)
+        prefix = action_i18n_prefix(context)
+        return unless prefix
+
+        [
+          prefix,
+          'meta',
+          i18n_segment(type),
+          i18n_segment(direction)
+        ].join('.')
+      end
+
+      def i18n_segment(value)
+        value.to_s.underscore.downcase.gsub(/[^a-z0-9_]+/, '_').gsub(/\A_+|_+\z/, '')
+      end
+
+      private
+
+      def action_i18n_prefix(context)
+        return unless context.respond_to?(:resource_path) && context.resource_path
+        return unless context.respond_to?(:action) && context.action
+
+        [
+          'resources',
+          *context.resource_path.map { |segment| i18n_segment(segment) },
+          'actions',
+          i18n_segment(context.action.action_name)
+        ].join('.')
+      end
+    end
+
     def initialize(direction, action)
       @direction = direction
       @params = []
@@ -171,7 +221,7 @@ module HaveAPI
       add_param(name, apply(kwargs, type: Custom, clean: block, symbolize_keys:))
     end
 
-    def describe(context, metadata: false)
+    def describe(context, metadata: false, i18n_path: nil)
       context.layout = layout
 
       ret = { parameters: {} }
@@ -179,8 +229,10 @@ module HaveAPI
       ret[:namespace] = namespace
       ret[:format] = @structure if @structure
 
+      i18n_path ||= self.class.action_i18n_path(context, @direction)
+
       @params.each do |p|
-        ret[:parameters][p.name] = p.describe(context)
+        ret[:parameters][p.name] = p.describe(context, i18n_path:)
       end
 
       ret[:parameters] = filtered_description_parameters(context, ret, metadata)
@@ -188,6 +240,23 @@ module HaveAPI
       ret
     end
 
+    def parameter_metadata_i18n_items(context, i18n_path: nil, meta_type: nil)
+      i18n_path ||= self.class.action_i18n_path(context, @direction)
+
+      @params.flat_map do |param|
+        next [] unless param.respond_to?(:metadata_i18n_catalog_items)
+
+        param.metadata_i18n_catalog_items(context, i18n_path).map do |item|
+          item.merge(
+            resource_path: Array(context.resource_path).map { |v| self.class.i18n_segment(v) },
+            action: self.class.i18n_segment(context.action.action_name),
+            direction: self.class.i18n_segment(@direction),
+            meta_type: meta_type && self.class.i18n_segment(meta_type)
+          )
+        end
+      end
+    end
+
     def validate_build
       m = :"validate_build_#{@direction}"
 
@@ -202,10 +271,10 @@ module HaveAPI
       value = namespace ? params[namespace] : params
 
       if value.nil?
-        raise ValidationError.new('invalid input layout', {}) if any_required_params?
+        raise ValidationError.new(HaveAPI.message('haveapi.validation.invalid_input_layout'), {}) if any_required_params?
 
       elsif !valid_layout?(value)
-        raise ValidationError.new('invalid input layout', {})
+        raise ValidationError.new(HaveAPI.message('haveapi.validation.invalid_input_layout'), {})
       end
 
       return unless namespace
@@ -231,7 +300,7 @@ module HaveAPI
           next if permitted && !permitted.include?(p.name)
 
           if p.required? && input[p.name].nil?
-            errors[p.name] = ['required parameter missing']
+            errors[p.name] = [HaveAPI.message('haveapi.validation.required_parameter_missing')]
             next
           end
 
@@ -248,7 +317,7 @@ module HaveAPI
                       end
           rescue ValidationError => e
             errors[p.name] ||= []
-            errors[p.name] << e.message
+            errors[p.name] << e.message_value
             next
           end
 
@@ -271,7 +340,7 @@ module HaveAPI
       end
 
       unless errors.empty?
-        raise ValidationError.new('input parameters not valid', errors)
+        raise ValidationError.new(HaveAPI.message('haveapi.validation.input_parameters_not_valid'), errors)
       end
 
       params

data/lib/haveapi/resource.rb

@@ -80,7 +80,7 @@ module HaveAPI
     end
 
     def self.describe(hash, context)
-      ret = { description: desc, actions: {}, resources: {} }
+      ret = { description: HaveAPI.localize(desc), actions: {}, resources: {} }
 
       context.resource = self
 

data/lib/haveapi/resources/action_state.rb

@@ -8,19 +8,25 @@ module HaveAPI::Resources
 
     params(:all) do
       id :id
-      string :label, label: 'Label'
-      bool :finished, label: 'Finished'
-      bool :status, label: 'Status',
-                    desc: 'Determines whether the action is proceeding or failing'
-      integer :current, label: 'Current progress'
-      integer :total, label: 'Total',
-                      desc: 'The action is finished when current equals to total'
-      string :unit, label: 'Unit', desc: 'Unit of current and total'
-      bool :can_cancel, label: 'Can cancel',
-                        desc: 'When true, execution of this action can be cancelled'
-      datetime :created_at, label: 'Created at'
-      datetime :updated_at, label: 'Updated at',
-                            desc: 'When was the progress last updated'
+      string :label, label: HaveAPI.message('haveapi.parameters.action_state.label.label')
+      bool :finished, label: HaveAPI.message('haveapi.parameters.action_state.finished.label')
+      bool :status,
+           label: HaveAPI.message('haveapi.parameters.action_state.status.label'),
+           desc: HaveAPI.message('haveapi.parameters.action_state.status.description')
+      integer :current, label: HaveAPI.message('haveapi.parameters.action_state.current.label')
+      integer :total,
+              label: HaveAPI.message('haveapi.parameters.action_state.total.label'),
+              desc: HaveAPI.message('haveapi.parameters.action_state.total.description')
+      string :unit,
+             label: HaveAPI.message('haveapi.parameters.action_state.unit.label'),
+             desc: HaveAPI.message('haveapi.parameters.action_state.unit.description')
+      bool :can_cancel,
+           label: HaveAPI.message('haveapi.parameters.action_state.can_cancel.label'),
+           desc: HaveAPI.message('haveapi.parameters.action_state.can_cancel.description')
+      datetime :created_at, label: HaveAPI.message('haveapi.parameters.action_state.created_at.label')
+      datetime :updated_at,
+               label: HaveAPI.message('haveapi.parameters.action_state.updated_at.label'),
+               desc: HaveAPI.message('haveapi.parameters.action_state.updated_at.description')
     end
 
     module Mixin
@@ -84,15 +90,25 @@ module HaveAPI::Resources
       route '{%{resource}_id}/poll'
 
       input(:hash) do
-        float :timeout, label: 'Timeout', desc: 'in seconds', default: 15, fill: true,
-                        number: { min: 0, max: MAX_TIMEOUT }
-        float :update_in, label: 'Progress',
-                          desc: 'number of seconds after which the state is returned if the progress ' \
-                                'has changed',
-                          nullable: true
-        bool :status, desc: 'status to check with if update_in is set', nullable: true
-        integer :current, desc: 'progress to check with if update_in is set', nullable: true
-        integer :total, desc: 'progress to check with if update_in is set', nullable: true
+        float :timeout,
+              label: HaveAPI.message('haveapi.parameters.action_state.poll.timeout.label'),
+              desc: HaveAPI.message('haveapi.parameters.action_state.poll.timeout.description'),
+              default: 15,
+              fill: true,
+              number: { min: 0, max: MAX_TIMEOUT }
+        float :update_in,
+              label: HaveAPI.message('haveapi.parameters.action_state.poll.update_in.label'),
+              desc: HaveAPI.message('haveapi.parameters.action_state.poll.update_in.description'),
+              nullable: true
+        bool :status,
+             desc: HaveAPI.message('haveapi.parameters.action_state.poll.status.description'),
+             nullable: true
+        integer :current,
+                desc: HaveAPI.message('haveapi.parameters.action_state.poll.current.description'),
+                nullable: true
+        integer :total,
+                desc: HaveAPI.message('haveapi.parameters.action_state.poll.total.description'),
+                nullable: true
       end
 
       output(:hash) do
@@ -103,7 +119,11 @@ module HaveAPI::Resources
 
       def exec
         if input[:timeout] > MAX_TIMEOUT
-          error!("timeout has to be maximally #{MAX_TIMEOUT}", {}, http_status: 400)
+          error!(
+            HaveAPI.message('haveapi.action_state.timeout_max', max: MAX_TIMEOUT),
+            {},
+            http_status: 400
+          )
         end
 
         t = Time.now
@@ -114,7 +134,7 @@ module HaveAPI::Resources
             id: path_params['action_state_id']
           )
 
-          error!('action state not found') unless state.valid?
+          error!(HaveAPI.message('haveapi.action_state.not_found')) unless state.valid?
 
           if state.finished? || (Time.now - t) >= input[:timeout]
             return state_to_hash(state)
@@ -153,7 +173,7 @@ module HaveAPI::Resources
 
         return state_to_hash(state) if state.valid?
 
-        error!('action state not found')
+        error!(HaveAPI.message('haveapi.action_state.not_found'))
       end
     end
 
@@ -172,7 +192,7 @@ module HaveAPI::Resources
           id: path_params['action_state_id']
         )
 
-        error!('action state not found') unless state.valid?
+        error!(HaveAPI.message('haveapi.action_state.not_found')) unless state.valid?
 
         ret = state.cancel
 
@@ -183,7 +203,7 @@ module HaveAPI::Resources
           ok!
 
         else
-          error!('cancellation failed')
+          error!(HaveAPI.message('haveapi.action_state.cancellation_failed'))
         end
       rescue RuntimeError, NotImplementedError => e
         error!(e.message)