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

Field is %n for the currency amount in words.

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

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 :

That’s all.

Example :

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

Parameter context provides :

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

Contributing to currency-in-words

Copyright © 2011 Bruno Carrere. See LICENSE.txt for further details.