i18n-message_format 0.1.0

data/lib/i18n/message_format/backend.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module I18n
+  module MessageFormat
+    # An I18n backend that parses and formats ICU MessageFormat patterns.
+    #
+    # {Backend} implements +I18n::Backend::Base+ and can be used standalone or
+    # chained with other backends via +I18n::Backend::Chain+. Translation
+    # values that are Strings are treated as ICU MessageFormat patterns; any
+    # extra options passed to {#translate} (beyond +scope+, +default+, and
+    # +separator+) are forwarded as format arguments.
+    #
+    # Non-String values (e.g. arrays or hashes used as scopes) are returned
+    # as-is without formatting.
+    #
+    # @example Standalone usage
+    #   backend = I18n::MessageFormat::Backend.new("config/locales/**/*.yml")
+    #   I18n.backend = backend
+    #   backend.load_translations
+    #   I18n.t("greeting", name: "Alice")  # => "Hello, Alice!"
+    #
+    # @example Chained with the default Simple backend
+    #   I18n.backend = I18n::Backend::Chain.new(
+    #     I18n::MessageFormat::Backend.new("config/locales/**/*.yml"),
+    #     I18n.backend
+    #   )
+    class Backend
+      include ::I18n::Backend::Base
+
+      # Creates a new backend that will load translations from the given
+      # file glob patterns.
+      #
+      # @param glob_patterns [Array<String>] one or more glob patterns passed
+      #   to +Dir.glob+ to locate YAML translation files
+      def initialize(*glob_patterns)
+        @glob_patterns = glob_patterns
+        @translations = {}
+        @cache = Cache.new
+      end
+
+      # Loads translations from all YAML files matching the glob patterns
+      # provided at construction time.
+      #
+      # Files are expected to be YAML documents whose top-level keys are locale
+      # codes (e.g. +en+, +fr+) mapping to a hash of translation keys and
+      # values.
+      #
+      # @return [void]
+      def load_translations
+        @glob_patterns.each do |pattern|
+          Dir.glob(pattern).each do |file|
+            data = YAML.safe_load_file(file, permitted_classes: [Symbol])
+            data.each do |locale, translations|
+              store_translations(locale.to_sym, translations)
+            end
+          end
+        end
+      end
+
+      # Merges +data+ into the in-memory translation store for +locale+.
+      #
+      # Nested hashes are flattened into dot-separated keys (e.g.
+      # +{ greeting: { hello: "Hi" } }+ becomes +{ :"greeting.hello" => "Hi" }+)
+      # before being merged.
+      #
+      # @param locale [Symbol, String] the locale to store translations for
+      # @param data [Hash] a (possibly nested) hash of translation keys/values
+      # @param options [Hash] currently unused; reserved for compatibility with
+      #   +I18n::Backend::Base+
+      # @return [void]
+      def store_translations(locale, data, options = {})
+        @translations[locale] ||= {}
+        deep_merge!(@translations[locale], flatten_hash(data))
+      end
+
+      # Looks up and formats the translation identified by +key+ for +locale+.
+      #
+      # String values are interpreted as ICU MessageFormat patterns and
+      # formatted with any extra keys in +options+ as arguments. Non-string
+      # values are returned unchanged.
+      #
+      # Throws +:exception+ with an +I18n::MissingTranslation+ object when the
+      # key is not found, which is the conventional signal for +I18n::Backend::Base+
+      # to trigger the default/fallback mechanism.
+      #
+      # @param locale [Symbol, String] the locale to translate for
+      # @param key [Symbol, String] the translation key
+      # @param options [Hash] format arguments plus the standard I18n options
+      #   (+:scope+, +:default+, +:separator+)
+      # @return [String, Object] the formatted translation string, or the raw
+      #   value if it is not a String
+      # @raise [I18n::MissingTranslation] (via +throw+) when the key is absent
+      def translate(locale, key, options = {})
+        pattern = lookup(locale, key, options[:scope], options)
+
+        if pattern.nil?
+          throw(:exception, ::I18n::MissingTranslation.new(locale, key, options))
+        end
+
+        return pattern unless pattern.is_a?(String)
+
+        arguments = options.reject { |k, _| [:scope, :default, :separator].include?(k) }
+        nodes = @cache.fetch(pattern) { Parser.new(pattern).parse }
+        Formatter.new(nodes, arguments, locale).format
+      end
+
+      # Returns the list of locales for which translations have been stored.
+      #
+      # @return [Array<Symbol>]
+      def available_locales
+        @translations.keys
+      end
+
+      # Returns +true+ if any translations have been loaded into the backend.
+      #
+      # @return [Boolean]
+      def initialized?
+        !@translations.empty?
+      end
+
+      protected
+
+      # Looks up a translation value by locale and key.
+      #
+      # @param locale [Symbol, String] the locale to look up
+      # @param key [Symbol, String] the translation key
+      # @param scope [Array, Symbol, nil] optional scope prepended to the key
+      # @param options [Hash] may include +:separator+ to override the default
+      #   key separator
+      # @return [Object, nil] the translation value, or +nil+ if not found
+      def lookup(locale, key, scope = [], options = {})
+        keys = ::I18n.normalize_keys(locale, key, scope, options[:separator])
+        keys.shift # remove locale
+
+        result = @translations[locale]
+        return nil unless result
+
+        keys.each do |k|
+          return nil unless result.is_a?(Hash)
+          result = result[k] || result[k.to_s]
+          return nil if result.nil?
+        end
+
+        result
+      end
+
+      private
+
+      def flatten_hash(hash, prefix = nil)
+        result = {}
+        hash.each do |key, value|
+          full_key = prefix ? :"#{prefix}.#{key}" : key.to_sym
+          if value.is_a?(Hash)
+            result.merge!(flatten_hash(value, full_key))
+          else
+            result[full_key] = value
+          end
+        end
+        result
+      end
+
+      def deep_merge!(base, override)
+        override.each do |key, value|
+          base[key] = value
+        end
+        base
+      end
+    end
+  end
+end

data/lib/i18n/message_format/cache.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module I18n
+  module MessageFormat
+    # A thread-safe, bounded LRU (Least Recently Used) cache.
+    #
+    # Used internally to memoize parsed ASTs so the same pattern string is
+    # only parsed once. The cache evicts the least recently accessed entry
+    # when the maximum size is reached.
+    class Cache
+      # Creates a new cache instance.
+      #
+      # @param max_size [Integer] maximum number of entries to retain before
+      #   evicting the least recently used entry (default: +1000+)
+      def initialize(max_size: 1000)
+        @max_size = max_size
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      # Retrieves the value stored under +key+, updating its recency.
+      #
+      # @param key [Object] the cache key
+      # @return [Object, nil] the cached value, or +nil+ if not found
+      def get(key)
+        @mutex.synchronize do
+          return nil unless @data.key?(key)
+          value = @data.delete(key)
+          @data[key] = value
+          value
+        end
+      end
+
+      # Stores +value+ under +key+, evicting the LRU entry if necessary.
+      #
+      # @param key [Object] the cache key
+      # @param value [Object] the value to store
+      # @return [Object] the stored value
+      def set(key, value)
+        @mutex.synchronize do
+          @data.delete(key) if @data.key?(key)
+          @data[key] = value
+          evict if @data.size > @max_size
+        end
+      end
+
+      # Returns the cached value for +key+, computing and storing it on a miss.
+      #
+      # @param key [Object] the cache key
+      # @yield called on a cache miss to compute the value to store
+      # @yieldreturn [Object] the value to cache and return
+      # @return [Object] the cached or newly computed value
+      def fetch(key)
+        value = get(key)
+        return value unless value.nil? && !@mutex.synchronize { @data.key?(key) }
+        value = yield
+        set(key, value)
+        value
+      end
+
+      # Removes all entries from the cache.
+      #
+      # @return [void]
+      def clear
+        @mutex.synchronize { @data.clear }
+      end
+
+      private
+
+      def evict
+        @data.delete(@data.keys.first)
+      end
+    end
+  end
+end

data/lib/i18n/message_format/formatter.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module I18n
+  module MessageFormat
+    # Raised when a placeholder in the pattern has no corresponding argument.
+    class MissingArgumentError < Error
+      # The name of the missing argument as it appeared in the pattern.
+      #
+      # @return [String]
+      attr_reader :argument_name
+
+      # @param argument_name [String] the name of the missing argument
+      def initialize(argument_name)
+        @argument_name = argument_name
+        super("Missing argument: #{argument_name}")
+      end
+    end
+
+    # Walks an AST produced by {Parser} and renders a formatted string.
+    #
+    # Each node type is dispatched to a dedicated format method. Number, date,
+    # and time formatting delegate to +I18n.localize+. Plural and ordinal
+    # categorisation uses rules registered under +i18n.plural.rule+ /
+    # +i18n.ordinal.rule+ in the active I18n backend, falling back to simple
+    # one/other logic when no rule is present.
+    class Formatter
+      # Creates a new formatter.
+      #
+      # @param nodes [Array] the AST returned by {Parser#parse}
+      # @param arguments [Hash] argument values keyed by Symbol
+      # @param locale [Symbol, String] locale used for pluralisation and
+      #   number/date/time formatting
+      def initialize(nodes, arguments, locale)
+        @nodes = nodes
+        @arguments = arguments
+        @locale = locale
+      end
+
+      # Renders the AST to a String.
+      #
+      # @return [String] the fully formatted message
+      # @raise [MissingArgumentError] if a required argument is absent from
+      #   the arguments hash
+      # @raise [Error] if a plural or select branch cannot be resolved
+      def format
+        format_nodes(@nodes)
+      end
+
+      private
+
+      def format_nodes(nodes)
+        nodes.map { |node| format_node(node) }.join
+      end
+
+      def format_node(node)
+        case node
+        when Nodes::TextNode
+          node.value
+        when Nodes::ArgumentNode
+          fetch_argument(node.name).to_s
+        when Nodes::NumberFormatNode
+          format_number(node)
+        when Nodes::DateFormatNode
+          format_date(node)
+        when Nodes::TimeFormatNode
+          format_time(node)
+        when Nodes::PluralNode
+          format_plural(node)
+        when Nodes::SelectNode
+          format_select(node)
+        when Nodes::SelectOrdinalNode
+          format_select_ordinal(node)
+        else
+          raise Error, "Unknown node type: #{node.class}"
+        end
+      end
+
+      def fetch_argument(name)
+        key = name.to_sym
+        unless @arguments.key?(key)
+          raise MissingArgumentError.new(name)
+        end
+        @arguments[key]
+      end
+
+      def format_number(node)
+        value = fetch_argument(node.name)
+        ::I18n.localize(value, locale: @locale)
+      rescue ::I18n::MissingTranslationData
+        value.to_s
+      end
+
+      def format_date(node)
+        value = fetch_argument(node.name)
+        opts = { locale: @locale }
+        opts[:format] = node.style.to_sym if node.style
+        ::I18n.localize(value, **opts)
+      end
+
+      def format_time(node)
+        value = fetch_argument(node.name)
+        opts = { locale: @locale }
+        opts[:format] = node.style.to_sym if node.style
+        ::I18n.localize(value, **opts)
+      end
+
+      def format_plural(node)
+        value = fetch_argument(node.name)
+        effective_value = value - node.offset
+
+        # Check exact matches first
+        exact_key = :"=#{value}"
+        if node.branches.key?(exact_key)
+          return format_branch(node.branches[exact_key], effective_value)
+        end
+
+        # Use i18n pluralization rules
+        category = pluralize_cardinal(effective_value, @locale)
+        branch = node.branches[category] || node.branches[:other]
+        raise Error, "No matching plural branch for '#{category}'" unless branch
+
+        format_branch(branch, effective_value)
+      end
+
+      def format_select(node)
+        value = fetch_argument(node.name)
+        key = value.to_s.to_sym
+        branch = node.branches[key] || node.branches[:other]
+        raise Error, "No matching select branch for '#{key}'" unless branch
+
+        format_nodes(branch)
+      end
+
+      def format_select_ordinal(node)
+        value = fetch_argument(node.name)
+        effective_value = value - node.offset
+
+        exact_key = :"=#{value}"
+        if node.branches.key?(exact_key)
+          return format_branch(node.branches[exact_key], effective_value)
+        end
+
+        category = pluralize_ordinal(effective_value, @locale)
+        branch = node.branches[category] || node.branches[:other]
+        raise Error, "No matching selectordinal branch for '#{category}'" unless branch
+
+        format_branch(branch, effective_value)
+      end
+
+      def format_branch(nodes, numeric_value)
+        nodes.map do |node|
+          if node.is_a?(Nodes::TextNode)
+            node.value.gsub("#", numeric_value.to_s)
+          else
+            format_node(node)
+          end
+        end.join
+      end
+
+      def pluralize_cardinal(count, locale)
+        rule = ::I18n.t(:"i18n.plural.rule", locale: locale, default: nil, resolve: false)
+        if rule.respond_to?(:call)
+          rule.call(count)
+        else
+          count == 1 ? :one : :other
+        end
+      end
+
+      def pluralize_ordinal(count, locale)
+        rule = ::I18n.t(:"i18n.ordinal.rule", locale: locale, default: nil, resolve: false)
+        if rule.respond_to?(:call)
+          rule.call(count)
+        else
+          :other
+        end
+      end
+    end
+  end
+end

data/lib/i18n/message_format/nodes.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module I18n
+  module MessageFormat
+    # Namespace for the AST node types produced by {Parser}.
+    #
+    # Each node is a +Struct+ whose members correspond to the semantic
+    # components of the ICU MessageFormat construct it represents.
+    module Nodes
+      # A literal text segment that requires no further processing.
+      #
+      # @!attribute [rw] value
+      #   @return [String] the literal text content
+      TextNode = Struct.new(:value)
+
+      # A simple argument placeholder, e.g. +{name}+.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name as it appears in the pattern
+      ArgumentNode = Struct.new(:name)
+
+      # A +{name, number}+ or +{name, number, style}+ argument.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name
+      # @!attribute [rw] style
+      #   @return [String, nil] optional number format style (e.g. +"integer"+)
+      NumberFormatNode = Struct.new(:name, :style)
+
+      # A +{name, date}+ or +{name, date, style}+ argument.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name
+      # @!attribute [rw] style
+      #   @return [String, nil] optional date format style (e.g. +"short"+)
+      DateFormatNode = Struct.new(:name, :style)
+
+      # A +{name, time}+ or +{name, time, style}+ argument.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name
+      # @!attribute [rw] style
+      #   @return [String, nil] optional time format style (e.g. +"short"+)
+      TimeFormatNode = Struct.new(:name, :style)
+
+      # A +{name, plural, ...}+ argument.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name
+      # @!attribute [rw] branches
+      #   @return [Hash{Symbol => Array<Nodes::TextNode, ...>}] plural branches
+      #     keyed by plural category (e.g. +:one+, +:other+) or exact-value
+      #     keys like +:=0+
+      # @!attribute [rw] offset
+      #   @return [Integer] value subtracted from the argument before
+      #     pluralisation (default: +0+)
+      PluralNode = Struct.new(:name, :branches, :offset) do
+        # @param name [String]
+        # @param branches [Hash]
+        # @param offset [Integer]
+        def initialize(name, branches, offset = 0)
+          super(name, branches, offset)
+        end
+      end
+
+      # A +{name, select, ...}+ argument.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name
+      # @!attribute [rw] branches
+      #   @return [Hash{Symbol => Array}] select branches keyed by selector
+      #     value, with an optional +:other+ fallback
+      SelectNode = Struct.new(:name, :branches)
+
+      # A +{name, selectordinal, ...}+ argument.
+      #
+      # @!attribute [rw] name
+      #   @return [String] the argument name
+      # @!attribute [rw] branches
+      #   @return [Hash{Symbol => Array}] ordinal plural branches keyed by
+      #     ordinal category (e.g. +:one+, +:two+, +:few+, +:other+) or
+      #     exact-value keys like +:=1+
+      # @!attribute [rw] offset
+      #   @return [Integer] value subtracted from the argument before
+      #     categorisation (default: +0+)
+      SelectOrdinalNode = Struct.new(:name, :branches, :offset) do
+        # @param name [String]
+        # @param branches [Hash]
+        # @param offset [Integer]
+        def initialize(name, branches, offset = 0)
+          super(name, branches, offset)
+        end
+      end
+    end
+  end
+end

data/lib/i18n/message_format/ordinal_rules.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module I18n
+  module MessageFormat
+    # Provides CLDR ordinal plural rules for use with +selectordinal+ arguments.
+    #
+    # Ordinal rules map a number to a category symbol (+:one+, +:two+, +:few+,
+    # +:other+, etc.) according to the Unicode CLDR ordinal plural rules for a
+    # given locale.
+    #
+    # Rules are installed into the active I18n backend under the
+    # +i18n.ordinal.rule+ key, where {Formatter} looks for them at runtime.
+    #
+    # @example Installing rules for English
+    #   I18n::MessageFormat::OrdinalRules.install(:en)
+    #
+    # @example Installing all bundled rules
+    #   I18n::MessageFormat::OrdinalRules.install_all
+    module OrdinalRules
+      # Built-in CLDR ordinal plural rules keyed by locale symbol.
+      #
+      # Each value is a +Proc+ that accepts an integer +n+ and returns the
+      # appropriate plural category symbol.
+      #
+      # @return [Hash{Symbol => Proc}]
+      RULES = {
+        en: lambda { |n|
+          mod10 = n % 10
+          mod100 = n % 100
+          if mod10 == 1 && mod100 != 11
+            :one
+          elsif mod10 == 2 && mod100 != 12
+            :two
+          elsif mod10 == 3 && mod100 != 13
+            :few
+          else
+            :other
+          end
+        }
+      }.freeze
+
+      # Installs the ordinal plural rule for +locale+ into the active I18n
+      # backend.
+      #
+      # Does nothing if no rule is defined for the given locale.
+      #
+      # @param locale [Symbol, String] the locale to install (e.g. +:en+)
+      # @return [void]
+      def self.install(locale)
+        rule = RULES[locale.to_sym]
+        return unless rule
+
+        ::I18n.backend.store_translations(locale, { i18n: { ordinal: { rule: rule } } })
+      end
+
+      # Installs ordinal plural rules for every locale in {RULES}.
+      #
+      # @return [void]
+      def self.install_all
+        RULES.each_key { |locale| install(locale) }
+      end
+    end
+  end
+end