Add English Readme

README_EN.md

@@ -0,0 +1,222 @@
+# JpPrefecture
+
+[![Gem Version](http://img.shields.io/gem/v/jp_prefecture.svg?style=flat)](https://rubygems.org/gems/jp_prefecture)
+[![Build Status](http://img.shields.io/travis/chocoby/jp_prefecture/master.svg?style=flat)](https://travis-ci.org/chocoby/jp_prefecture)
+[![Coveralls](https://img.shields.io/coveralls/chocoby/jp_prefecture.svg)](https://coveralls.io/r/chocoby/jp_prefecture)
+[![Code Climate](https://img.shields.io/codeclimate/github/chocoby/jp_prefecture.svg)](https://codeclimate.com/github/chocoby/jp_prefecture)
+[![Dependency Status](http://img.shields.io/gemnasium/chocoby/jp_prefecture.svg?style=flat)](https://gemnasium.com/chocoby/jp_prefecture)
+
+https://rubygems.org/gems/jp_prefecture
+
+## Description
+
+Convert prefecture code to prefecture name in Japan.
+
+Based on JIS X 0402. Remove 0 when prefecture code start with 0.
+
+```
+Hokkaido: 01 -> 1
+Tokyo: 13 -> 13
+```
+
+Reference(Japanese): [Wikipedia: 全国地方公共団体コード](http://ja.wikipedia.org/wiki/%E5%85%A8%E5%9B%BD%E5%9C%B0%E6%96%B9%E5%85%AC%E5%85%B1%E5%9B%A3%E4%BD%93%E3%82%B3%E3%83%BC%E3%83%89#.E9.83.BD.E9.81.93.E5.BA.9C.E7.9C.8C.E3.82.B3.E3.83.BC.E3.83.89)
+
+You can change prefecture code and prefecture name's mapping data. Please check this [Customize mapping data]
+
+Also available as a Rails plugin
+
+## Usage
+
+### Requirement
+
+```ruby
+require 'jp_prefecture'
+```
+
+### Search Prefecture by Code
+
+Provide prefecture code to search prefecture's data
+
+```ruby
+pref = JpPrefecture::Prefecture.find 13
+# => #<JpPrefecture::Prefecture:0x007fceb11927d8 @code=13, @name="東京都", @name_e="Tokyo", @name_h="とうきょうと", @name_k="トウキョウト", @zips=[1000000..2080035], @area="関東">
+pref.code
+# => 13
+pref.name
+# => "東京都"
+pref.name_e
+# => "Tokyo"
+pref.name_h
+# => "とうきょうと"
+pref.name_k
+# => "トウキョウト"
+pref.area
+# => "関東"
+```
+
+以下のように書くことも可能です:
+
+```ruby
+JpPrefecture::Prefecture.find code: 13
+```
+
+### Search by Prefecture Name
+
+```ruby
+JpPrefecture::Prefecture.find name: "東京都"
+JpPrefecture::Prefecture.find name: "Tokyo"
+JpPrefecture::Prefecture.find name: "tokyo"
+JpPrefecture::Prefecture.find name: "トウキョウト"
+JpPrefecture::Prefecture.find name: "とうきょうと"
+JpPrefecture::Prefecture.find name: "東京"
+```
+
+### All Prefectures
+
+```ruby
+JpPrefecture::Prefecture.all
+# => [#<JpPrefecture::Prefecture:0x007fceb119a2a8 @code=1, @name="北海道", @name_e="Hokkaido", @name_h="ほっかいどう", @name_k="ホッカイドウ", @zips=[10000..70895, 400000..996509], @area="北海道">, ...]
+```
+
+### Usage on Rails (ActiveRecord)
+
+Include JpPrefecture to Model which `ActiveRecord::Base` inherited.
+
+app/models/place.rb:
+
+```ruby
+class Place < ActiveRecord::Base
+  # prefecture_code:integer
+
+  include JpPrefecture
+  jp_prefecture :prefecture_code
+end
+```
+
+By JpPrefecture included, `prefecture` method will be generated:
+
+```ruby
+place = Place.new
+place.prefecture_code = 13
+place.prefecture.name_e
+# => "Tokyo"
+```
+
+Customize `prefecture` method name with `method_name` option:
+
+```ruby
+# model
+jp_prefecture :prefecture_code, method_name: :pref
+
+place = Place.new
+place.prefecture_code = 13
+place.pref.name_e
+# => "Tokyo"
+```
+
+### Template usage
+
+Use `collection_select` to generate selector in view:
+
+```ruby
+# Selector prefecture name in English
+f.collection_select :prefecture_code, JpPrefecture::Prefecture.all, :code, :name_e
+
+# Selector prefecture name in Japanese
+f.collection_select :prefecture_code, JpPrefecture::Prefecture.all, :code, :name
+```
+
+### Migration
+
+Set `prefecture_code` column type to `integer` or `string`.
+
+Example:
+
+```ruby
+class AddPrefectureCodeToPlaces < ActiveRecord::Migration
+  def change
+    add_column :places, :prefecture_code, :integer
+  end
+end
+```
+
+### Customize Mapping Data
+
+Customize mapping data with `custom_mapping_path`.
+
+```ruby
+custom_mapping_path = "..." # /path/to/mapping_data
+
+JpPrefecture.setup do |config|
+  config.mapping_data = YAML.load_file custom_mapping_path
+end
+```
+
+Check out [prefecture.yml](https://github.com/chocoby/jp_prefecture/blob/master/data/prefecture.yml) for data format.
+
+
+## Installation
+
+Add line below in Gemfile.
+
+```ruby
+gem 'jp_prefecture'
+```
+
+Run
+
+```
+$ bundle
+```
+
+Or install gem with `gem install`
+
+```
+$ gem install jp_prefecture
+```
+
+
+## Documentation
+
+[http://rdoc.info/github/chocoby/jp_prefecture/master/frames/index](http://rdoc.info/github/chocoby/jp_prefecture/master/frames/index)
+
+## Supports
+
+* Ruby: 1.9.3 / 2.0.0 / 2.1 / 2.2 / 2.3
+* Rails: 3.2 / 4.0 / 4.1 / 4.2 / 5.0
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+
+## Test
+
+```
+git clone https://github.com/chocoby/jp_prefecture.git
+cd jp_prefecture
+bundle install --path .bundle
+bundle exec rspec
+```
+
+Run test in multiple `ActiveRecord` versions
+
+```
+bundle exec appraisal install
+bundle exec appraisal rake spec
+```
+
+
+## GitHub
+
+https://github.com/chocoby/jp_prefecture
+
+
+## License
+
+[MIT License](http://chocoby.mit-license.org/)