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”).
Add the gem to your Gemfile.
: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).
=> 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)
- 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
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
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).
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 © 2011 Bruno Carrere. See LICENSE.txt for further details.