currency-in-words

Provides a view helper for Rails that displays a currency amount in words (eg. number_to_currency_in_words(100) => ‘one hundred dollars’).

This helper comes with two supported locales (English and French) but it is possible and easy to implement your own (see “Implementing a new locale”).

Installation

Add the gem to your Gemfile.

gem 'currency-in-words'

Usage

General Options

:locale - Sets the locale to be used for formatting (defaults to current locale).
:currency - Sets the denomination of the currency (defaults to :default currency for the locale or “dollar” if not set).
:connector - Sets the connector between integer part and decimal part of the currency (defaults to “, ”).
:format - Sets the format for non-negative numbers (defaults to “%n”).

Field is %n for the currency amount in words.

:negative_format - Sets the format for negative numbers (defaults to prepending “minus” to the number in words ‘minus %n’).

Field is %n for the currency amount in words (same as format).

Examples

number_to_currency_in_words(123456.50): => one hundred and twenty-three thousand four hundred and fifty-six dollars, fifty cents
number_to_currency_in_words(123456.50, connector: ' and '): => one hundred and twenty-three thousand four hundred and fifty-six dollars and fifty cents
number_to_currency_in_words(123456.50, locale: :fr, connector: ' et '): => cent vingt-trois mille quatre cent cinquante-six dollars et cinquante cents
number_to_currency_in_words(80300.80, locale: :fr, currency: :euro, connector: ' et '): => quatre-vingt mille trois cents euros et quatre-vingts centimes

Specifics options for locale :en

:delimiter - Sets the thousands delimiter (defaults to false)
:skip_and - Skips the ‘and’ part in number - US (defaults to false)

Examples

number_to_currency_in_words(201201201.201, delimiter: true): => two hundred and one million, two hundred and one thousand, two hundred and one dollars, twenty cents
number_to_currency_in_words(201201201.201, delimiter: true, skip_and: true): => two hundred one million, two hundred one thousand, two hundred one dollars, twenty cents

Options settings

Modify config/locales/xx.yml to set default options and add currencies for locales.

Example for locale :en

en:
  number:
    currency_in_words:
      connector: ' and '
      negative_format: '(%n)'
      skip_and: true
      delimiter: true
      currencies:
        euro: 
          unit:
            one: 'euro'
            many: 'euros'
          decimal: 
            one: 'cent'
            many: 'cents'
        pound:
          unit:
            one: 'pound'
            many: 'pounds'
          decimal: 
            one: 'penny'
            many: 'pence'

Example for locale :fr

fr:
  number:
    currency_in_words:
      format: '%n'
      negative_format: 'moins %n'
      connector: ' et '
      currencies:
        default:             # euro will be the default currency for locale :fr
          unit:
            one: 'euro'
            many: 'euros'    # can be omit
            more: "d'euros"  # can be omit (specific to :fr, eg. 'un million d'euros')
          decimal: 
            one: 'centime'
            many: 'centimes' # can be omit
        dollar:
          unit:
            one: 'dollar'
            many: 'dollars'
          decimal: 
            one: 'cent'
            many: 'cents'
        livre:
          unit:
            feminine: true   # specific to :fr, eg. 'un euro' but 'une livre'
            one: 'livre'
            many: 'livres'
          decimal: 
            one: 'penny'
            many: 'pence'

Implementing a new locale

CurrencyInWords expects a texterizer by locale. A texterizer is a simple class that returns the amount in words for the currency and the given locale (eg. a class EnTexterizer for English locale, a class FrTexterizer for French locale). So, for example, if you want to support Italian, you have to implement an ItTexterizer class for the module CurrencyInWords.

A texterizer :

must provide a texterize method
must return a string

That’s all.

Example :

class CurrencyInWords::ItTexterizer
  def texterize(context)
    ../..
  end
end

Parameter context provides :

an array that includes the integer part and the decimal part of the number (context.number_parts)
a hash that includes the options passed to number_to_currency_in_words (context.options).

See the source code of EnTexterizer for an example (FrTexterizer is perhaps too specific but EnTexterizer can be a starting point to implement your own texterizer).

If you need more options for your language, simply create yours and use them (options :delimiter and :skip_and are for example specifics to EnTexterizer while :feminine is specific to FrTexterizer).

ToDo

clean up and push tests
add comments in source code

Contributing to currency-in-words

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

currency-in-words

Installation

Usage

General Options

Examples

Specifics options for locale :en

Examples

Options settings

Example for locale :en

Example for locale :fr

Implementing a new locale

ToDo

Contributing to currency-in-words

Copyright