human_number 0.1.0

data/README.md

@@ -0,0 +1,323 @@
+# HumanNumber
+
+HumanNumber is a Ruby gem that implements accurate number formatting based on international standards. It references Microsoft Globalization documentation and Unicode CLDR standards to provide human-readable number formats that respect the unique formatting conventions of each country and region.
+
+## Features
+
+- 🌍 **International Standards Compliance**: Based on Microsoft Globalization and Unicode CLDR standards
+- 🔢 **Cultural Number Systems**: Automatic selection of Western (K/M/B/T), East Asian (천/만/억/조), or Indian (lakh/crore) systems
+- 💰 **Currency Formatting**: ISO 4217 currency codes with native locale precision rules
+- 🏗️ **Intelligent Abbreviations**: Culturally-appropriate large number simplification
+- 🔧 **Rails Integration**: Complete compatibility with Rails I18n infrastructure
+- 📚 **rails-i18n Based**: Leverages verified locale data
+
+## Quick Start
+
+Add to your Gemfile and install:
+
+```ruby
+gem 'human_number'
+```
+
+```bash
+bundle install
+```
+
+Start formatting numbers:
+
+```ruby
+require 'human_number'
+
+# Human-readable numbers
+HumanNumber.human_number(1_234_567)           #=> "1.2M"
+HumanNumber.human_number(50_000, locale: :ko) #=> "5만"
+
+# Currency formatting
+HumanNumber.currency(1234.56, currency_code: 'USD', locale: :en) #=> "$1,234.56"
+HumanNumber.human_currency(1_234_567, currency_code: 'USD', locale: :en) #=> "$1.2M"
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'human_number'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install human_number
+```
+
+## API Reference
+
+### Core Methods
+
+#### `HumanNumber.human_number(number, **options)` 
+
+Formats numbers with intelligent, culturally-appropriate abbreviations.
+
+```ruby
+# Basic usage
+HumanNumber.human_number(1_234_567)           #=> "1.2M"
+HumanNumber.human_number(50_000, locale: :ko) #=> "5만"
+HumanNumber.human_number(50_000, locale: :ja) #=> "5万"
+
+# Precision control (default: max_digits: 2)
+HumanNumber.human_number(1_234_567, max_digits: 1)   #=> "1M"
+HumanNumber.human_number(1_234_567, max_digits: 3)   #=> "1.23M"
+HumanNumber.human_number(1_234_567, max_digits: nil) #=> "1M 234K 567"
+
+# Unit preferences (Western locales only)
+HumanNumber.human_number(1_000_000, abbr_units: true)  #=> "1M"
+HumanNumber.human_number(1_000_000, abbr_units: false) #=> "1 million"
+
+# Minimum thresholds
+HumanNumber.human_number(5_000, min_unit: 10_000)  #=> "5000"
+HumanNumber.human_number(50_000, min_unit: 10_000) #=> "50K"
+
+# Zero trimming (default: true)
+HumanNumber.human_number(1_000_000, trim_zeros: true)  #=> "1M"
+HumanNumber.human_number(1_000_000, trim_zeros: false) #=> "1.0M"
+```
+
+**Parameters:**
+- `locale` (Symbol): Target locale for cultural number systems
+- `max_digits` (Integer|nil): Maximum significant digits (default: 2, nil for complete mode)
+- `abbr_units` (Boolean): Use abbreviated vs full units (default: true)
+- `min_unit` (Integer): Minimum unit threshold for abbreviation (default: nil)
+- `trim_zeros` (Boolean): Remove trailing decimal zeros (default: true)
+
+#### `HumanNumber.currency(number, currency_code:, locale:)`
+
+Standard currency formatting with native locale precision rules.
+
+```ruby
+HumanNumber.currency(1234.56, currency_code: 'USD', locale: :en) #=> "$1,234.56"
+HumanNumber.currency(50_000, currency_code: 'KRW', locale: :ko)  #=> "50,000원"
+HumanNumber.currency(1234.99, currency_code: 'JPY', locale: :ja) #=> "1,235円"
+
+# Cross-locale consistency (USD always 2 decimals, JPY always 0)
+HumanNumber.currency(1234.56, currency_code: 'USD', locale: :ko) #=> "$1,234.56"  
+HumanNumber.currency(1234.56, currency_code: 'JPY', locale: :en) #=> "1,235円"
+```
+
+#### `HumanNumber.human_currency(number, currency_code:, locale:, **options)`
+
+Human-readable currency formatting with cultural abbreviations.
+
+```ruby
+HumanNumber.human_currency(1_234_567, currency_code: 'USD', locale: :en) #=> "$1.2M"
+HumanNumber.human_currency(50_000, currency_code: 'KRW', locale: :ko)    #=> "5만원"
+
+# Combined options
+HumanNumber.human_currency(1_234_567, currency_code: 'USD', locale: :en, max_digits: 3) #=> "$1.23M"
+HumanNumber.human_currency(1_234_567, currency_code: 'USD', locale: :en, max_digits: nil) #=> "$1M 234K 567"
+```
+
+### Rails Integration
+
+In Rails applications, helper methods are automatically available:
+
+```erb
+<%= human_number(1_234_567) %>                         <!-- 1.2M -->
+<%= human_currency(1_234_567, currency_code: 'USD') %> <!-- $1.2M -->
+<%= currency(1234.56, currency_code: 'USD') %>         <!-- $1,234.56 -->
+
+<!-- With options -->
+<%= human_number(1_234_567, max_digits: 3, locale: :ko) %> <!-- 123만 -->
+<%= number_to_human_size(1_234_567) %>                     <!-- 1.2M (legacy) -->
+```
+
+## Cultural Number Systems
+
+Different cultures have fundamentally different concepts for large numbers:
+
+### Western System (K/M/B/T)
+**Used by:** English, German, French, Spanish, Italian, Portuguese, Russian, Dutch, Swedish, Danish, Norwegian
+
+```ruby
+HumanNumber.human_number(1_234_567, locale: :en) #=> "1.2M"
+HumanNumber.human_number(1_000_000_000, locale: :en) #=> "1B"
+```
+
+**Units:** thousand (1,000), million (1,000,000), billion (1,000,000,000), trillion (1,000,000,000,000)
+
+### East Asian System (千/万/億/兆)  
+**Used by:** Korean (ko), Japanese (ja), Chinese (zh, zh-CN, zh-TW)
+
+```ruby
+HumanNumber.human_number(1_234_567, locale: :ko) #=> "123만"  
+HumanNumber.human_number(1_234_567, locale: :ja) #=> "123万"
+HumanNumber.human_number(100_000_000, locale: :ko) #=> "1억"
+```
+
+**Units:** 천/千 (thousand), 만/万 (ten thousand), 억/億 (hundred million), 조/兆 (trillion)
+
+### Indian System (lakh/crore)
+**Used by:** Hindi (hi), Urdu (ur), Bengali (bn), Indian English (en-IN)
+
+```ruby
+HumanNumber.human_number(100_000, locale: :hi) #=> "1 lakh"
+HumanNumber.human_number(10_000_000, locale: :hi) #=> "1 crore"
+```
+
+**Units:** thousand (1,000), lakh (100,000), crore (10,000,000)
+
+The gem automatically selects the appropriate system based on locale, ensuring cultural accuracy.
+
+## Architecture & Design Philosophy
+
+### Direct Method Design
+
+HumanNumber uses direct class methods rather than instance-based objects for simplicity:
+
+```ruby
+# Direct approach (current)
+HumanNumber.human_number(1234567, locale: :ko, max_digits: 2)
+
+# Instance approach (rejected)
+formatter = HumanNumber::Formatter.new(locale: :ko, max_digits: 2)
+formatter.format(1234567)
+```
+
+**Why Direct Methods?**
+- **Simplicity**: Clean, straightforward API
+- **Thread Safety**: No shared mutable state
+- **Rails Compatibility**: Matches Rails helper patterns
+
+### Separation of Concerns
+
+HumanNumber uses a two-stage formatting process:
+
+1. **Number Formatting**: Converts numbers to human-readable strings with cultural units
+2. **Currency Application**: Applies currency symbols and format strings
+
+```ruby
+# Internal flow for HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en)
+formatted_number = Formatters::Number.format(1234567, locale: :en, max_digits: 2)     #=> "1.2M"
+final_result = Formatters::Currency.format("1.2M", currency_code: 'USD', locale: :en) #=> "$1.2M"
+```
+
+This separation enables:
+- **Independent testing** of number vs currency logic  
+- **Reusability** of number formatting for non-currency contexts
+- **Maintainability** when adding new currencies or number systems
+
+### Centralized Locale Logic
+
+Currency-locale relationships are managed centrally in `LocaleSupport`:
+
+```ruby
+CURRENCY_NATIVE_LOCALES = {
+  "USD" => [:en], "EUR" => %i[de fr es it nl], 
+  "KRW" => [:ko], "JPY" => [:ja]
+  # ... 40+ currencies
+}
+```
+
+This ensures:
+- **Consistent precision rules**: USD always shows 2 decimals, JPY shows 0
+- **Smart fallbacks**: When user locale doesn't match currency's native locale
+- **Easy maintenance**: New currencies require only one mapping entry
+
+### Configuration-Free Design
+
+HumanNumber deliberately avoids runtime configuration in favor of explicit parameters:
+
+```ruby
+# No global configuration
+HumanNumber.human_number(1234567, locale: :ko, max_digits: 2)
+
+# Application defaults handled at application level
+class ApplicationController
+  def format_money(amount, currency)
+    HumanNumber.human_currency(amount, currency_code: currency, locale: I18n.locale, max_digits: 2)
+  end
+end
+```
+
+**Benefits:**
+- No shared state or thread safety concerns
+- Predictable behavior (each call is independent)
+- Easier testing (no configuration setup/teardown)
+
+## Development
+
+After checking out the repo:
+
+```bash
+$ cd human_number
+$ bundle install
+$ rake spec
+```
+
+Run tests:
+```bash
+$ rake spec
+```
+
+Run linting:
+```bash
+$ rake rubocop
+```
+
+Run all quality checks:
+```bash
+$ rake  # Runs both spec and rubocop
+```
+
+## Contributing
+
+1. Fork it (https://github.com/yourusername/human_number/fork)
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+### Contribution Guidelines
+
+- Please write tests when adding new features
+- Follow RuboCop style guidelines  
+- Write clear and descriptive commit messages
+- Update documentation for API changes
+- Ensure 100% test coverage for new features
+
+### Adding New Locales
+
+To add support for a new locale:
+
+1. Add locale to appropriate number system in `lib/human_number/formatters/number.rb`
+2. Create locale file in `config/locales/` with unit translations
+3. Add currency mapping to `CURRENCY_NATIVE_LOCALES` if applicable
+4. Add comprehensive tests
+
+## License
+
+MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Standards Reference
+
+This project is based on the following international standards and documentation:
+
+- [Microsoft Globalization - Number Formatting](https://learn.microsoft.com/en-us/globalization/locale/number-formatting) - Cultural number formatting standards
+- [Microsoft Globalization - Currency Formats](https://learn.microsoft.com/en-us/globalization/locale/currency-formats) - Currency formatting standards  
+- [Unicode CLDR](http://cldr.unicode.org/) - Locale data standards
+- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - Currency code standards
+- [rails-i18n](https://github.com/svenfuchs/rails-i18n) - Rails internationalization support
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for details.
+
+## Issues
+
+Please report bugs and feature requests at [GitHub Issues](https://github.com/yourusername/human_number/issues).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/config/locales/bn.yml

@@ -0,0 +1,8 @@
+bn:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "হাজার"       # hazar
+          lakh: "লক্ষ"          # lakh
+          crore: "কোটি"         # koti

data/config/locales/de.yml

@@ -0,0 +1,9 @@
+de:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "T"      # Tausend
+          million: "M"       # Million  
+          billion: "Mrd"     # Milliarde
+          trillion: "B"      # Billion (German billion = English trillion)

data/config/locales/en-GB.yml

@@ -0,0 +1,10 @@
+en-GB:
+  number:
+    human:
+      decimal_units:
+        # UK style guide prefers lowercase abbreviations
+        abbr_units:
+          thousand: "k"
+          million: "m"
+          billion: "bn"
+          trillion: "tn"

data/config/locales/en-IN.yml

@@ -0,0 +1,8 @@
+en-IN:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "K"
+          lakh: "L"             # lakh (100,000)  
+          crore: "Cr"           # crore (10,000,000)

data/config/locales/en.yml

@@ -0,0 +1,10 @@
+en:
+  number:
+    human:
+      decimal_units:
+        # Abbreviated units for space-constrained contexts (K/M/B/T)
+        abbr_units:
+          thousand: "K"
+          million: "M"
+          billion: "B"
+          trillion: "T"

data/config/locales/es.yml

@@ -0,0 +1,9 @@
+es:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "K"
+          million: "M"
+          billion: "B" 
+          trillion: "T"

data/config/locales/fr.yml

@@ -0,0 +1,9 @@
+fr:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "k"
+          million: "M"
+          billion: "G"    # milliard in French
+          trillion: "T"

data/config/locales/hi.yml

@@ -0,0 +1,8 @@
+hi:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "हज़ार"       # hazaar
+          lakh: "लाख"           # lakh (100,000)
+          crore: "करोड़"         # crore (10,000,000)

data/config/locales/ja.yml

@@ -0,0 +1,15 @@
+ja:
+  number:
+    currency:
+      format:
+        native_format: "%n%u"
+        native_unit: "円"
+        format: "%u%n"
+        unit: "¥"
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "千"
+          ten_thousand: "万"
+          hundred_million: "億"
+          trillion: "兆"

data/config/locales/ko.yml

@@ -0,0 +1,15 @@
+ko:
+  number:
+    currency:
+      format:
+        native_format: "%n%u"
+        native_unit: "원"
+        format: "%u%n"
+        unit: "₩"
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "천"
+          ten_thousand: "만"
+          hundred_million: "억"
+          trillion: "조"

data/config/locales/ur.yml

@@ -0,0 +1,8 @@
+ur:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "ہزار"
+          lakh: "لاکھ"
+          crore: "کروڑ"

data/config/locales/zh-CN.yml

@@ -0,0 +1,9 @@
+zh-CN:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "千"
+          ten_thousand: "万"
+          hundred_million: "亿"    # Simplified Chinese
+          trillion: "兆"

data/config/locales/zh-TW.yml

@@ -0,0 +1,9 @@
+zh-TW:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "千"
+          ten_thousand: "萬"       # Traditional Chinese
+          hundred_million: "億"    # Traditional Chinese
+          trillion: "兆"

data/config/locales/zh.yml

@@ -0,0 +1,12 @@
+zh:
+  number:
+    currency:
+      format:
+        native_unit: "¥"
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "千"
+          ten_thousand: "万"
+          hundred_million: "亿"    # Simplified Chinese
+          trillion: "兆"

data/human_number.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/human_number/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "human_number"
+  spec.version = HumanNumber::VERSION
+  spec.authors = ["Your Name"]
+  spec.email = ["your.email@example.com"]
+
+  spec.summary = "International standard-based number formatting for Ruby applications"
+  spec.description = "HumanNumber implements accurate number formatting based on international standards " \
+                     "including Microsoft Globalization documentation and Unicode CLDR. Provides human-readable " \
+                     "number formats with precise locale-specific decimal separators, thousand separators, " \
+                     "currency formats, and cultural number conventions."
+  spec.homepage = "https://github.com/yourusername/human_number"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/yourusername/human_number"
+  spec.metadata["changelog_uri"] = "https://github.com/yourusername/human_number/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "actionview", ">= 5.2"
+  spec.add_dependency "i18n", ">= 1.6", "< 2"
+  spec.add_dependency "rails-i18n", ">= 5.1"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/lib/human_number/formatters/currency.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "../locale_support"
+
+module HumanNumber
+  module Formatters
+    class Currency
+      extend ActionView::Helpers::NumberHelper
+
+      class << self
+        # Internal formatter for applying currency symbols to pre-formatted number strings.
+        # All parameters are required - use HumanNumber.currency/human_currency for user-friendly interface.
+        #
+        # @param formatted_number [String] Pre-formatted number string
+        # @param currency_code [String] ISO 4217 currency code
+        # @param locale [Symbol, String] Locale for currency symbol and format rules
+        # @return [String] Formatted currency string with symbol and proper placement
+        #
+        # @api private
+        def format(formatted_number, currency_code:, locale:)
+          locale = locale.to_sym
+
+          # Use shared locale logic to determine display locale
+          display_locale = HumanNumber::LocaleSupport.primary_locale_for_currency(currency_code, locale)
+
+          # Apply currency formatting to the already formatted number
+          apply_currency_formatting(formatted_number, currency_code, display_locale)
+        end
+
+        private
+
+        def apply_currency_formatting(formatted_number, currency_code, locale)
+          # Get currency symbol
+          symbol = lookup_currency_symbol(currency_code, locale)
+
+          # Get currency format
+          format_string = lookup_currency_format(currency_code, locale)
+
+          # Handle negative numbers - move negative sign outside currency symbol
+          if formatted_number.start_with?("-")
+            clean_number = formatted_number[1..]
+            result = format_string.gsub("%u", symbol).gsub("%n", clean_number)
+            "-#{result}"
+          else
+            format_string.gsub("%u", symbol).gsub("%n", formatted_number)
+          end
+        end
+
+        def lookup_currency_symbol(currency_code, locale)
+          # Use internal locale support to get currency symbol
+          symbol = lookup_i18n_value(:unit, locale:, currency_code:)
+          return symbol if symbol
+
+          # Final fallback to currency code
+          currency_code
+        end
+
+        def lookup_currency_format(currency_code, locale)
+          # Use internal locale support to get currency format
+          format = lookup_i18n_value(:format, locale:, currency_code:)
+
+          # Fallback to simple format for unknown currencies
+          format || "%u%n"
+        end
+
+        # Currency locale lookup methods using shared LocaleSupport
+        def lookup_i18n_value(key, locale:, currency_code:)
+          HumanNumber::LocaleSupport.lookup_currency_i18n_value(key, locale:, currency_code:)
+        end
+      end
+    end
+  end
+end