== CountrySelectEngine

A Rails engine to provide localized country names, languages and currencies. For example, it translates 'en' to 'English' for language, 'USD' to 'US Dollar' for currency and 'US' to 'United States' for country.

It uses Rails internationalization framework (http://rails-i18n.org) for translation. It requires Rails 3.2 or later

You can easily translate country codes in your application like this:

   <%= I18n.t 'US', :scope => 'countries' %>  

And to create selection menu:

   <%= localized_country_select(:user, :country, [], :include_blank => 'Please choose...') %>  

will become:

  <select name="user[country]" id="user_country">
  <option value="">Please choose...</option>
  <option disabled="disabled" value="">-------------</option>
  <option value="AF">Afghanistan</option>
  ...
  <option value="ZW">Zimbabwe</option>
  </select>  

You can do the same for language ('en', 'ja', 'fr', etc.) and currency ('USD', 'GBP', 'EUR', etc.)

== Install

Add this gem in Gemfile of your application

  gem 'country-select-engine'

or any variation with :path or :git

== Generating translation files

The translation files are generated through ruby-cldr:

  thor cldr:download
  thor cldr:export --merge

Then 'script/convert_cldr.rb' is used to tidy up.

== Generating translation files (deprecated)

If you want to regenerate your own, in your application, use

    rake country_select:import_country[locales]

or in dummy application of this engine

    rake app:country_select:import_country[locales]

Country names are imported from Unicode.org's CLDR repository (http://www.unicode.org/cldr/data/charts/summary/root.html)

Don't forget to restart the application when you add new locale.

== ActionView helper

ActionView helper code is adapted from Rails' default *country_select* plugin (previously in core).
See http://github.com/rails/country_select/tree/master/lib/country_select.rb

== Options

@:exclude@ option

  <%= localized_country_select(:user, :country, ['English'], :include_blank => 'Please choose...', :exclude => ['Afrikaans']) %>  

@:only@ option

  <%= localized_country_select(:user, :country, ['English'], :include_blank => 'Please choose...', :only => ['German', 'French']) %>  

@:symbol@ option

':symbol => :pretend' to prepend symbol to value in selection
':symbol => :append' to append symbol to value in selection

== Framework usage

This engine should also integrate nicely with various formbuilders, including Formtastic

Formtastic example:

<%= semantic_form_for @user do |form| %>  
  ...
  <%= form.input :home_country, :as => :country, :priority_countries => ['USA'], :include_blank => 'Please choose country...', :only => ['USA', 'Germany', 'France']) %>    
  ...
<% end %>  

== Copyright

- Copyright (c) 2012 Yen-Ju Chen, released under the MIT license
- Copyright (c) 2008 Karel Minarik (www.karmi.cz), released under the MIT license

== Other resources

* http://github.com/rails/country_select (Default Rails plugin)
* http://github.com/russ/country_code_select (Stores country code, not name)
* http://github.com/onomojo/i18n-country-translations
* http://github.com/onomojo/i18n_country_select