human_number 0.1.0

data/lib/human_number/formatters/number.rb

@@ -0,0 +1,462 @@
+# frozen_string_literal: true
+
+require_relative "../locale_support"
+
+module HumanNumber
+  module Formatters
+    class Number
+      extend ActionView::Helpers::NumberHelper
+
+      # Constants for string literals and magic numbers
+      ZERO_STRING = "0"
+      EMPTY_SEPARATOR = ""
+      SPACE_SEPARATOR = " "
+      DECIMAL_FORMAT_TEMPLATE = "%.%df"
+      MINIMUM_UNIT_COUNT = 1.0
+      SINGLE_DIGIT_LIMIT = 1
+
+      # I18n key templates
+      I18N_DECIMAL_UNITS_KEY = "number.human.decimal_units"
+      I18N_ABBR_UNITS_SECTION = "abbr_units"
+      I18N_UNITS_SECTION = "units"
+
+      class << self
+        # Internal formatter for numbers with intelligent abbreviations.
+        # All parameters are required - use HumanNumber.human_number for user-friendly interface.
+        #
+        # @param number [Numeric] Number to format
+        # @param locale [Symbol, String] Locale for unit system selection
+        # @param abbr_units [Boolean] Use abbreviated symbols vs full words
+        # @param max_digits [Integer, nil] Max digits after decimal, nil for complete mode
+        # @param min_unit [Integer, nil] Minimum unit threshold for abbreviation
+        # @param trim_zeros [Boolean] Remove trailing decimal zeros
+        # @return [String] Formatted number string
+        #
+        # @api private
+        def format(number, locale:, abbr_units:, max_digits:, min_unit:, trim_zeros:)
+          locale = locale.to_sym
+
+          # Direct delegation to appropriate system class
+          system_class = determine_system_class(locale)
+          system_class.format_number(
+            number,
+            locale:,
+            abbr_units:,
+            max_digits:,
+            min_unit:,
+            trim_zeros:
+          )
+        end
+
+        # Default options for human number formatting
+        def default_options
+          {
+            abbr_units: true,
+            max_digits: 2,
+            min_unit: nil,
+            trim_zeros: true,
+          }.freeze
+        end
+
+        # Default options for currency number formatting (tighter display)
+        def default_currency_number_options
+          {
+            abbr_units: true,
+            max_digits: 1,
+            min_unit: nil,
+            trim_zeros: true,
+          }.freeze
+        end
+
+        # Formats a number using Rails' currency precision rules for the given currency.
+        # This ensures consistent precision regardless of display locale.
+        #
+        # @param number [Numeric] The number to format
+        # @param currency_code [String] ISO 4217 currency code
+        # @param locale [Symbol] Display locale (for context)
+        # @return [String] Formatted number with currency-appropriate precision
+        def format_with_currency_precision(number, currency_code:, locale:)
+          locale = locale.to_sym
+
+          # Use currency's native locale for precision rules
+          precision_locale = LocaleSupport.currency_precision_locale(currency_code, locale)
+
+          I18n.with_locale(precision_locale) do
+            number_to_currency(number, format: "%n", locale: precision_locale)
+          end
+        end
+
+        private
+
+        def determine_system_class(locale)
+          locale_sym = locale.to_sym
+
+          case locale_sym
+          when *EastAsianSystem::TARGET_LOCALES
+            EastAsianSystem
+          when *IndianSystem::TARGET_LOCALES
+            IndianSystem
+          else
+            DefaultSystem
+          end
+        end
+      end
+
+      # Default number system (thousand, million, billion, trillion)
+      class DefaultSystem
+        TARGET_LOCALES = %i[en es fr de it pt ru nl sv da no].freeze
+
+        UNIT_DEFINITIONS = [
+          { key: :trillion, divisor: 1_000_000_000_000 },
+          { key: :billion, divisor: 1_000_000_000 },
+          { key: :million, divisor: 1_000_000 },
+          { key: :thousand, divisor: 1_000 },
+        ].freeze
+
+        class << self
+          def format_number(number, locale:, abbr_units: true, min_unit: nil, max_digits: 2, trim_zeros: true)
+            return ZERO_STRING if number.zero?
+
+            parts = if max_digits.nil?
+                      format_in_complete_mode(number, locale, abbr_units, min_unit)
+                    else
+                      format_in_abbreviated_mode(number, locale, abbr_units, max_digits, trim_zeros, min_unit)
+                    end
+
+            return number.to_s if parts.nil?
+
+            finalize_result(number, parts)
+          end
+
+          def format_in_complete_mode(number, locale, abbr_units, min_unit)
+            # Complete mode shows all units: "1M 234K 567"
+            unit_breakdown = break_down_into_all_units(number)
+            units_above_threshold = filter_by_minimum_unit_threshold(unit_breakdown, min_unit)
+            return nil if units_above_threshold.empty?
+
+            format_all_unit_parts(units_above_threshold, locale, abbr_units)
+          end
+
+          def format_in_abbreviated_mode(number, locale, abbr_units, max_digits, trim_zeros, min_unit)
+            # Abbreviated mode shows single largest unit: "1.2M"
+            unit_breakdown = break_down_into_largest_unit(number)
+            units_above_threshold = filter_by_minimum_unit_threshold(unit_breakdown, min_unit)
+            return nil if units_above_threshold.empty?
+
+            format_abbreviated_unit_parts(units_above_threshold, locale, abbr_units, max_digits, trim_zeros)
+          end
+
+          private
+
+          def breakdown_number(number)
+            result = []
+            remaining = number.abs
+
+            unit_definitions.each do |unit|
+              next unless remaining >= unit[:divisor]
+
+              count = remaining.to_f / unit[:divisor]
+              result << { unit_key: unit[:key], count: count, divisor: unit[:divisor] }
+              break # Only use the largest applicable unit
+            end
+
+            # If no unit matched, use the raw number
+            result << { unit_key: :units, count: remaining, divisor: 1 } if result.empty?
+
+            result
+          end
+
+          # Find the largest applicable unit for abbreviated display
+          # Example: 1,234,567 -> [{million: 1.234567}]
+          def break_down_into_largest_unit(number)
+            absolute_amount = number.abs
+
+            # Find the first (largest) unit where the count would be >= 1.0
+            unit_definitions.each do |unit|
+              unit_count = absolute_amount.to_f / unit[:divisor]
+
+              return [create_unit_part(unit[:key], unit_count, unit[:divisor])] if unit_count >= MINIMUM_UNIT_COUNT
+            end
+
+            # If no unit is applicable, return the raw number
+            [create_unit_part(:units, absolute_amount, 1)]
+          end
+
+          def unit_definitions
+            UNIT_DEFINITIONS
+          end
+
+          # Helper method to create consistent unit part structure
+          def create_unit_part(unit_key, count, divisor)
+            { unit_key: unit_key, count: count, divisor: divisor }
+          end
+
+          # Filter out units below the minimum threshold
+          def filter_by_minimum_unit_threshold(breakdown, min_unit)
+            return breakdown unless min_unit
+
+            breakdown.select { |unit_info| unit_info[:divisor] >= min_unit }
+          end
+
+          # Format unit parts for abbreviated display (e.g., "1.2M")
+          def format_abbreviated_unit_parts(breakdown, locale, abbr_units, max_digits, trim_zeros)
+            breakdown.map do |unit_info|
+              if unit_info[:unit_key] == :units
+                # Raw numbers don't need significant digits rounding
+                format_raw_number_count(unit_info[:count], max_digits, trim_zeros)
+              else
+                # Format with unit symbol (e.g., "1.2" + "M" = "1.2M")
+                format_number_with_unit_symbol(unit_info, locale, abbr_units, max_digits, trim_zeros)
+              end
+            end
+          end
+
+          # Format raw number without unit symbols
+          def format_raw_number_count(count, max_digits, trim_zeros)
+            format_unit_count(count, max_digits:, trim_zeros:, apply_rounding: false)
+          end
+
+          # Format number with unit symbol (e.g., "1.2M")
+          def format_number_with_unit_symbol(unit_info, locale, abbr_units, max_digits, trim_zeros)
+            symbol = lookup_unit_symbol(locale, unit_info[:unit_key], abbr_units)
+            format_with_symbol(unit_info[:count], symbol, abbr_units, max_digits:, trim_zeros:)
+          end
+
+          # Format unit with symbol for complete mode (e.g., "234K")
+          def format_complete_unit_with_symbol(unit_info, locale, abbr_units)
+            symbol = lookup_unit_symbol(locale, unit_info[:unit_key], abbr_units)
+            count_text = unit_info[:count].to_i.to_s
+            separator = determine_unit_value_separator(abbr_units)
+            formatted_symbol = apply_symbol_formatting_rules(symbol, abbr_units)
+            "#{count_text}#{separator}#{formatted_symbol}"
+          end
+
+          def format_unit_count(count, max_digits: 2, trim_zeros: true, apply_rounding: true)
+            return count.to_s unless count.is_a?(Numeric)
+
+            rounded = apply_rounding ? round_to_significant_digits(count, max_digits) : count
+
+            format_rounded_count(rounded, max_digits, trim_zeros, apply_rounding, count)
+          end
+
+          def format_rounded_count(rounded, max_digits, trim_zeros, apply_rounding, original_count)
+            if trim_zeros
+              format_with_trimmed_zeros(rounded)
+            elsif apply_rounding
+              format_with_fixed_decimals(rounded, max_digits)
+            else
+              original_count.to_s
+            end
+          end
+
+          def format_with_trimmed_zeros(rounded)
+            if rounded == rounded.to_i
+              rounded.to_i.to_s
+            else
+              rounded.to_s
+            end
+          end
+
+          def format_with_fixed_decimals(rounded, max_digits)
+            integer_digits = rounded.to_i.to_s.length
+            decimal_places = [0, max_digits - integer_digits].max
+            format("%.#{decimal_places}f", rounded)
+          end
+
+          def round_to_significant_digits(number, digits)
+            return handle_edge_cases(number, digits) if should_handle_edge_case?(number, digits)
+
+            abs_num = number.abs
+            int_digits = count_integer_digits(abs_num.to_i)
+
+            result = calculate_significant_digits_result(abs_num, digits, int_digits)
+            apply_sign(number, result)
+          end
+
+          def should_handle_edge_case?(number, digits)
+            number.zero? || digits <= 0
+          end
+
+          def handle_edge_cases(number, _digits)
+            return 0.0 if number.zero?
+
+            number
+          end
+
+          def calculate_significant_digits_result(abs_num, digits, int_digits)
+            if int_digits >= digits
+              truncate_to_digits(abs_num.to_i, digits)
+            else
+              round_with_decimals(abs_num, digits, int_digits)
+            end
+          end
+
+          def apply_sign(original_number, result)
+            original_number.negative? ? -result : result
+          end
+
+          def count_integer_digits(int_part)
+            int_part.zero? ? SINGLE_DIGIT_LIMIT : int_part.to_s.length
+          end
+
+          def truncate_to_digits(int_part, digits)
+            int_part.to_s[0, digits].to_i.to_f
+          end
+
+          def round_with_decimals(abs_num, digits, int_digits)
+            decimal_places = digits - int_digits
+            (abs_num * (10**decimal_places)).round / (10**decimal_places).to_f
+          end
+
+          # Look up the localized symbol for a unit (e.g., 'M' for million)
+          def lookup_unit_symbol(locale, unit_key, abbr_units)
+            section = abbr_units ? I18N_ABBR_UNITS_SECTION : I18N_UNITS_SECTION
+
+            I18n.t("#{I18N_DECIMAL_UNITS_KEY}.#{section}.#{unit_key}", locale:, default: nil) ||
+              I18n.t("#{I18N_DECIMAL_UNITS_KEY}.#{section}.#{unit_key}", locale: :en, default: nil) ||
+              unit_key.to_s.upcase
+          end
+
+          def format_with_symbol(value, symbol, abbr_units, max_digits: 2, trim_zeros: true)
+            # Apply significant digits rounding to unit values
+            formatted_count = format_unit_count(value, max_digits:, trim_zeros:, apply_rounding: true)
+            separator = determine_unit_value_separator(abbr_units)
+            formatted_symbol = apply_symbol_formatting_rules(symbol, abbr_units)
+            "#{formatted_count}#{separator}#{formatted_symbol}"
+          end
+
+          # Determine separator between number and unit ("1M" vs "1 million")
+          def determine_unit_value_separator(abbr_units)
+            abbr_units ? EMPTY_SEPARATOR : SPACE_SEPARATOR
+          end
+
+          # Apply locale-specific formatting rules to unit symbols
+          def apply_symbol_formatting_rules(symbol, abbr_units)
+            return symbol if abbr_units || symbol.length <= 1
+
+            symbol.downcase # Western lowercase rule for full words
+          end
+
+          # Break down number into all applicable units for complete display
+          # Example: 1,234,567 -> [{million: 1}, {thousand: 234}, {units: 567}]
+          def break_down_into_all_units(number)
+            unit_breakdown = UnitBreakdown.new(number.abs, unit_definitions)
+            unit_breakdown.extract_all_units
+          end
+
+          # Helper class to manage unit breakdown state
+          class UnitBreakdown
+            def initialize(amount, unit_definitions)
+              @remaining_amount = amount
+              @unit_definitions = unit_definitions
+              @unit_parts = []
+            end
+
+            def extract_all_units
+              extract_major_units
+              add_remaining_as_units
+              @unit_parts
+            end
+
+            private
+
+            def extract_major_units
+              @unit_definitions.each do |unit|
+                extract_single_unit(unit) if @remaining_amount >= unit[:divisor]
+              end
+            end
+
+            def extract_single_unit(unit)
+              unit_count = (@remaining_amount / unit[:divisor]).to_i
+              return if unit_count.zero?
+
+              @unit_parts << create_unit_part(unit[:key], unit_count, unit[:divisor])
+              @remaining_amount %= unit[:divisor]
+            end
+
+            def add_remaining_as_units
+              return unless @remaining_amount.positive?
+
+              @unit_parts << create_unit_part(:units, @remaining_amount, 1)
+            end
+
+            def create_unit_part(unit_key, count, divisor)
+              { unit_key: unit_key, count: count, divisor: divisor }
+            end
+          end
+
+          # Format unit parts for complete display (e.g., "1M 234K 567")
+          def format_all_unit_parts(breakdown, locale, abbr_units)
+            breakdown.map do |unit_info|
+              if unit_info[:unit_key] == :units
+                # Raw numbers shown as integers in complete mode
+                unit_info[:count].to_i.to_s
+              else
+                # Format each unit part with its symbol
+                format_complete_unit_with_symbol(unit_info, locale, abbr_units)
+              end
+            end
+          end
+
+          # Apply sign and join all parts into final result
+          def finalize_result(number, formatted_parts)
+            combined_result = formatted_parts.join(SPACE_SEPARATOR)
+            number.negative? ? "-#{combined_result}" : combined_result
+          end
+        end
+      end
+
+      # East Asian number system (thousand, ten_thousand, hundred_million, trillion)
+      class EastAsianSystem < DefaultSystem
+        TARGET_LOCALES = %i[ko ja zh zh-CN zh-TW].freeze
+
+        UNIT_DEFINITIONS = [
+          { key: :trillion, divisor: 1_000_000_000_000 },
+          { key: :hundred_million, divisor: 100_000_000 },
+          { key: :ten_thousand, divisor: 10_000 },
+          { key: :thousand, divisor: 1_000 },
+        ].freeze
+
+        class << self
+          private
+
+          def unit_definitions
+            UNIT_DEFINITIONS
+          end
+
+          def format_with_symbol(value, symbol, _abbr_units, max_digits: 2, trim_zeros: true)
+            # East Asian: no separator regardless of abbr_units
+            # Apply significant digits rounding to unit values
+            formatted_count = format_unit_count(value, max_digits:, trim_zeros:, apply_rounding: true)
+            formatted_symbol = apply_symbol_formatting_rules(symbol, true)
+            "#{formatted_count}#{formatted_symbol}"
+          end
+
+          # Keep original case for Asian characters (만, 억, 조)
+          def apply_symbol_formatting_rules(symbol, _abbr_units)
+            symbol
+          end
+        end
+      end
+
+      # Indian subcontinent number system (thousand, lakh, crore)
+      class IndianSystem < DefaultSystem
+        TARGET_LOCALES = %i[hi ur bn en-IN].freeze
+
+        UNIT_DEFINITIONS = [
+          { key: :crore, divisor: 10_000_000 },
+          { key: :lakh, divisor: 100_000 },
+          { key: :thousand, divisor: 1_000 },
+        ].freeze
+
+        class << self
+          private
+
+          def unit_definitions
+            UNIT_DEFINITIONS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/human_number/locale_support.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module HumanNumber
+  # Shared locale support logic for both Number and Currency formatters.
+  #
+  # This module provides centralized currency-to-locale mappings and locale
+  # resolution logic to ensure consistent precision and formatting rules
+  # across different formatters.
+  module LocaleSupport
+    # Mapping of currency codes to their primary native locales
+    # Used to determine appropriate precision and formatting rules
+    CURRENCY_NATIVE_LOCALES = {
+      "KRW" => [:ko],
+      "JPY" => [:ja],
+      "USD" => [:en],
+      "EUR" => %i[de fr es it nl],
+      "GBP" => %i[en en-GB],
+      "CAD" => %i[en en-CA fr fr-CA],
+      "CNY" => %i[zh zh-CN],
+      "CHF" => %i[de fr it],
+      "INR" => %i[hi en],
+      "RUB" => [:ru],
+      "BRL" => %i[pt pt-BR],
+      "MXN" => [:es],
+      "AUD" => %i[en en-AU],
+      "NZD" => %i[en en-NZ],
+      "SEK" => [:sv],
+      "NOK" => %i[no nb],
+      "DKK" => [:da],
+      "SGD" => %i[en en-SG zh zh-SG],
+      "HKD" => %i[zh zh-HK en en-HK],
+      "ZAR" => %i[en en-ZA af],
+      "TRY" => [:tr],
+      "ARS" => %i[es es-AR],
+      "IDR" => [:id],
+      "THB" => [:th],
+      "MYR" => %i[ms en en-MY],
+      "PHP" => %i[en en-PH tl],
+      "VND" => [:vi],
+    }.freeze
+
+    # Keys supported for native currency formatting
+    SUPPORTED_NATIVE_CURRENCY_KEYS = %i[unit format native_format].freeze
+
+    module_function
+
+    # Returns the primary locale for displaying a currency.
+    # If the user's locale matches a native locale for the currency, use it.
+    # Otherwise, use the first native locale for the currency.
+    #
+    # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
+    # @param user_locale [Symbol] User's preferred locale
+    # @return [Symbol] Primary locale for currency display
+    def primary_locale_for_currency(currency_code, user_locale)
+      locales = native_locales_for_currency(currency_code)
+      (locales.include?(user_locale.to_sym) ? user_locale.to_sym : locales.first) || :en
+    end
+
+    # Returns the locale to use for currency precision rules in standard formatting.
+    # Always returns the currency's primary native locale to ensure consistent
+    # precision (e.g., USD always shows 2 decimals, JPY shows 0 decimals).
+    #
+    # @param currency_code [String] ISO 4217 currency code
+    # @param user_locale [Symbol] User's preferred locale (for context)
+    # @return [Symbol] Locale for precision rules
+    def currency_precision_locale(currency_code, _user_locale = nil)
+      native_locales_for_currency(currency_code).first || :en
+    end
+
+    # Checks if a locale is considered native for a given currency.
+    #
+    # @param currency_code [String] ISO 4217 currency code
+    # @param locale [Symbol] Locale to check
+    # @return [Boolean] Whether the locale is native for the currency
+    def native_locale?(currency_code, locale)
+      return false unless currency_code && locale
+
+      native_locales_for_currency(currency_code).include?(locale.to_sym)
+    end
+
+    # Returns all native locales for a given currency.
+    #
+    # @param currency_code [String] ISO 4217 currency code
+    # @return [Array<Symbol>] Array of native locales for the currency
+    def native_locales_for_currency(currency_code)
+      currency_code = currency_code&.upcase
+      CURRENCY_NATIVE_LOCALES[currency_code] || []
+    end
+
+    # Generates the I18n key for native currency formatting.
+    #
+    # @param key [Symbol] Currency format key (:unit, :format, etc.)
+    # @return [String] I18n key for native currency formatting
+    def native_currency_key(key)
+      "number.currency.format.native_#{key}"
+    end
+
+    # Generates the I18n key for standard currency formatting.
+    #
+    # @param key [Symbol] Currency format key (:unit, :format, etc.)
+    # @return [String] I18n key for standard currency formatting
+    def currency_key(key)
+      "number.currency.format.#{key}"
+    end
+
+    # Looks up currency-related I18n values with native locale fallback.
+    #
+    # @param key [Symbol] Currency format key to look up
+    # @param locale [Symbol] Display locale
+    # @param currency_code [String] ISO 4217 currency code
+    # @return [String, nil] I18n value or nil if not found
+    def lookup_currency_i18n_value(key, locale:, currency_code:)
+      # Return nil for unknown currencies so formatters can fall back appropriately
+      return nil if native_locales_for_currency(currency_code).empty?
+
+      if SUPPORTED_NATIVE_CURRENCY_KEYS.include?(key) && native_locale?(currency_code, locale)
+        native_key = native_currency_key(key)
+
+        return I18n.t(native_key, locale:) if I18n.exists?(native_key, locale)
+      end
+
+      I18n.t(currency_key(key), locale: primary_locale_for_currency(currency_code, locale))
+    end
+  end
+end

data/lib/human_number/rails/helpers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module HumanNumber
+  module Rails
+    # Rails view helpers for human-readable number and currency formatting.
+    #
+    # These helpers provide convenient access to HumanNumber functionality
+    # within Rails views and controllers with Rails-friendly parameter handling.
+    module Helpers
+      # Formats a number with intelligent, locale-aware abbreviations.
+      #
+      # This is a Rails helper wrapper around HumanNumber.human_number that provides
+      # Rails-friendly parameter handling with optional locale detection.
+      #
+      # @param number [Numeric] The number to format
+      # @param locale [Symbol, String, nil] The locale for formatting (default: current I18n locale)
+      # @param options [Hash] Additional formatting options
+      # @option options [Boolean] :abbr_units (true) Use abbreviated unit symbols
+      # @option options [Integer, nil] :max_digits (1) Maximum significant digits
+      # @option options [Integer, nil] :min_unit (nil) Minimum unit threshold
+      # @option options [Boolean] :trim_zeros (true) Remove trailing decimal zeros
+      #
+      # @return [String] The formatted number string
+      #
+      # @example Basic usage in views
+      #   <%= human_number(1234567) %>                    #=> "1.2M"
+      #   <%= human_number(50000, locale: :ko) %>         #=> "5만"
+      #   <%= human_number(1234567, max_digits: 2) %>     #=> "1.23M"
+      #
+      # @see HumanNumber.human_number Main implementation
+      def human_number(number, locale: nil, **options)
+        locale ||= I18n.locale
+        HumanNumber.human_number(number, locale:, **options)
+      end
+
+      # Formats a currency amount using standard Rails currency formatting.
+      #
+      # This helper provides Rails-friendly parameter handling for currency formatting
+      # with automatic locale detection and parameter normalization.
+      #
+      # @param number [Numeric] The amount to format
+      # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
+      # @param locale [Symbol, String, nil] Display locale (default: current I18n locale)
+      #
+      # @return [String] The formatted currency string
+      #
+      # @example Basic usage in views
+      #   <%= currency(1234.56, currency_code: 'USD') %>           #=> "$1,234.56"
+      #   <%= currency(50000, currency_code: 'KRW', locale: :ko) %> #=> "50,000원"
+      #   <%= currency(1234.99, currency_code: 'JPY') %>           #=> "1,235円"
+      #
+      # @see HumanNumber.currency Main implementation
+      def currency(number, currency_code:, locale: nil)
+        locale ||= I18n.locale
+        HumanNumber.currency(number, currency_code:, locale:)
+      end
+
+      # Formats a currency amount with intelligent, locale-aware abbreviations.
+      #
+      # This helper combines human-readable number formatting with currency symbols,
+      # providing Rails-friendly access to abbreviated currency formatting.
+      #
+      # @param number [Numeric] The amount to format
+      # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
+      # @param locale [Symbol, String, nil] Locale for formatting (default: current I18n locale)
+      # @param options [Hash] Additional formatting options
+      # @option options [Boolean] :abbr_units (true) Use abbreviated unit symbols
+      # @option options [Integer, nil] :max_digits (1) Maximum significant digits
+      # @option options [Integer, nil] :min_unit (nil) Minimum unit threshold
+      # @option options [Boolean] :trim_zeros (true) Remove trailing decimal zeros
+      #
+      # @return [String] The formatted currency string with abbreviations
+      #
+      # @example Basic usage in views
+      #   <%= human_currency(1234567, currency_code: 'USD') %>                    #=> "$1.2M"
+      #   <%= human_currency(50000, currency_code: 'KRW', locale: :ko) %>         #=> "5만원"
+      #   <%= human_currency(1234567, currency_code: 'USD', max_digits: 2) %>     #=> "$1.23M"
+      #   <%= human_currency(1000000, currency_code: 'USD', abbr_units: false) %> #=> "$1 million"
+      #
+      # @see HumanNumber.human_currency Main implementation
+      def human_currency(number, currency_code:, locale: nil, **options)
+        locale ||= I18n.locale
+        HumanNumber.human_currency(number, currency_code:, locale:, **options)
+      end
+
+      # Legacy alias for human_number to maintain backward compatibility.
+      #
+      # @deprecated Use {#human_number} instead
+      # @param number [Numeric] The number to format
+      # @param options [Hash] Formatting options (Rails-style hash)
+      # @return [String] The formatted number string
+      def number_to_human_size(number, **options)
+        locale = options.delete(:locale) || I18n.locale
+        human_number(number, locale:, **options)
+      end
+    end
+  end
+end