README.md in locale_setter-0.3.0 vs README.md in locale_setter-0.4.0
- old
+ new
@@ -1,11 +1,16 @@
# LocaleSetter
-`LocaleSetter` sets the locale for the current request in a Rails application.
+`LocaleSetter` sets the locale for the current request in a web application.
+Rails has automatic support, other applications can use LocaleSetter with a
+bit of configuration.
## Installation
+Currently, LocaleSetter only supports Rails 3.2 and up. If you want 3.0 or
+3\.1 support, please file an Issue and we can work it out.
+
### Gem Installation
Add this line to your application's Gemfile:
```ruby
@@ -18,56 +23,64 @@
$ bundle
```
### Rails Application Configuration
-Include the module in your `app/controllers/application_controller.rb`:
+There is none! Thanks, Railties!
-```ruby
-class ApplicationController < ActionController::Base
- protect_from_forgery
-
- include LocaleSetter::Rails
-end
-```
-
-*Note:* If you have before filters or a module that handles user authentication, have that _above_ this new `include` so it happens first.
-
### Non-Rails Applications
The library can be used outside of Rails by accessing `LocaleSetter::Generic` directly. You need to pass in your I18n class and the data sources, like this:
```
# Example Input Data
request = {'HTTP_ACCEPT_LANGUAGE' = 'en,es;0.6'}
params = {:locale = 'en'}
user = User.first
-i18n = I18n
+i18n = I18n
# Set the .locale of I18n
LocaleSetter::Generic.set_locale(i18n,
{:env => request,
:params => params,
- :user => user})
+ :user => user,
+ :domain => domain})
```
-The `i18n.locale=` will be called with the local selected from the passed data. `:env`, `:params`, and `:user` are all optional.
+The `i18n.locale=` will be called with the local selected from the passed data. `:env`, `:params`, `:domain` and `:user` are all optional.
## How It Works
One of the challenges with internationalization is knowing which locale a user actually wants. We recommend the following hierarchy of sources:
1. URL Parameter
2. User Preference
-3. HTTP Headers
-4. Default
+3. Domain Specific
+4. HTTP Headers
+5. Default
+### Configuration
+
+`LocaleSetter` can be configured via a block. Here are the defaults:
+
+```ruby
+LocaleSetter.configure do |config|
+ config.url_param = :locale
+ config.user_locale_method = :locale
+ config.localized_domains = {}
+ config.current_user_method = :current_user
+end
+```
+
+So if you want to change the defaults then call this method any time after
+the library is loaded, like in a Rails initializer.
+
### URL Parameter
As a developer or designer, it's incredibly handy to be able to manipulate the URL to change locales. You might even use this with CI to run your integration tests using each locale you support.
-If you're currently using the default locale for the application, generated URLs on your site will be untouched.
+If you're currently using the default locale for the application, generated URLs on your site will be untouched.
For example, say my default is `:en` for English and I am viewing in English, my URL might look like:
```
http://example.com/articles/1
@@ -103,18 +116,20 @@
http://example.com/articles/1&locale=es
```
#### Non-Supported Locales
-If the locale specified in the URL is not supported, `LocaleSetter` will revert to the default locale.
+If the locale specified in the URL is not supported, `LocaleSetter` will revert to the default locale.
Note that care has been taken to prevent a symbol-table-overflow denial of service attack. Unsupported locales are not symbolized, so there is no danger.
### User Preference
If your system has authentication, then you likely use have a `current_user` helper method available. `LocaleSetter` will call `locale` on current user, expecting to get back a string response.
+Both method names(`current_user` & `locale`) can be changed via a config block.
+
#### Storing a User Preference
The easiest solution is to add a column to your users table:
```
@@ -130,22 +145,24 @@
<% end %>
```
Remember that you may need to modify the `user.rb` if you're filtering mass-assignment parameters.
-#### Using a Different Method / Column
+### Locale-per-domain
-`LocaleSetter::User` can be configured to call a method other than `.locale` on the user.
+You could specify prefered locale according to the domain (or subdomain).
+Just specify domains hash via config block:
-Anytime after the library is loaded, like in a Rails initializer, use the `locale_method=` method:
-
```ruby
-LocaleSetter::User.locale_method = :my_locale
+LocaleSetter.configure do |config|
+ config.localized_domains = {
+ "en.domain.com" => :en,
+ "es.domain.com" => :es
+ }
+end
```
-Subsequent calls to `LocaleSetter::User.for` will use the specified method.
-
### HTTP Headers
Every request coming into your web server includes a ton of header information. One key/value pair looks like this:
```
@@ -174,6 +191,6 @@
Check out https://github.com/jcasimir/locale_setter_test for a simple Rails application used to black-box test the library in real usage.
## License
-Please see the included LICENSE.txt
\ No newline at end of file
+Please see the included LICENSE.txt