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.

Copyright

Copyright (c) 2011 Bruno Carrere. See LICENSE.txt for further details.