Permalink
Browse files

Update readme.

  • Loading branch information...
1 parent 7715f8a commit 8702c3666310e5fd707f2bff9ec27300f8c7c212 @DouweM DouweM committed Sep 6, 2013
Showing with 39 additions and 31 deletions.
  1. +39 −31 README.md
View
@@ -1,61 +1,70 @@
# HttpAcceptLanguage
-A small effort in making a plugin which helps you detect the users preferred language, as sent by the HTTP header.
+A gem which helps you detect the users preferred language, as sent by the "Accept-Language" HTTP header.
-Since version 2.0, this gem is Rack middleware.
-
-## Features
-
-* Splits the http-header into languages specified by the user
-* Returns empty array if header is illformed.
-* Corrects case to xx-XX
-* Sorted by priority given, as much as possible.
-* Gives you the most important language
-* Gives compatible languages
+The algorithm is based on [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html), with one exception:
+when a user requests "en-US" and "en" is an available language, "en" is deemed compatible with "en-US".
+The RFC specifies that the requested language must either exactly match the available language or must exactly match a prefix of the available language. This means that when the user requests "en" and "en-US" is available, "en-US" would be compatible, but not the other way around. This is usually not what you're looking for.
-See also: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
+Since version 2.0, this gem is Rack middleware.
## Example
-When using in Rails:
+The `http_accept_language` method is available in any controller:
-``` ruby
+```ruby
class SomeController < ApplicationController
-
def some_action
-
- http_accept_language.user_preferred_languages # => [ 'nl-NL', 'nl-BE', 'nl', 'en-US', 'en' ]
- available = %w{en en-US nl-BE}
+ http_accept_language.user_preferred_languages # => %w(nl-NL nl-BE nl en-US en)
+ available = %w(en en-US nl-BE)
http_accept_language.preferred_language_from(available) # => 'nl-BE'
- http_accept_language.user_preferred_languages # => [ 'en-GB']
- available = %w{en-US}
+ http_accept_language.user_preferred_languages # => %w(en-GB)
+ available = %w(en-US)
http_accept_language.compatible_language_from(available) # => 'en-US'
+ http_accept_language.user_preferred_languages # => %w(nl-NL nl-BE nl en-US en)
+ available = %w(en nl de) # This could be from I18n.available_locales
+ http_accept_language.preferred_language_from(available) # => 'nl'
end
-
end
```
-Older versions of Rails (pre 3.0) might need to include the middleware manually.
+You can easily set the locale used for i18n in a before-filter:
-Usage in any Rack application, simple add the middleware:
+```ruby
+class SomeController < ApplicationController
+ before_filter :set_locale
+
+ private
+ def set_locale
+ I18n.locale = http_accept_language.compatible_language_from(I18n.available_locales)
+ end
+end
+```
+
+To use the middleware in any Rack application, simply add the middleware:
``` ruby
require 'http_accept_language'
use HttpAcceptLanguage::Middleware
run YourAwesomeApp
```
-Then you can access it:
+Then you can access it from `env`:
``` ruby
class YourAwesomeApp
- def self.call(env)
+ def initialize(app)
+ @app = app
+ end
+
+ def call(env)
available = %w(en en-US nl-BE)
language = env.http_accept_language.preferred_language_from(available)
- [ 200, {}, ["Oh, you speak #{language}!"]]
+
+ [200, {}, ["Oh, you speak #{language}!"]]
end
end
@@ -65,23 +74,22 @@ end
* **user_preferred_languages**:
Returns a sorted array based on user preference in HTTP_ACCEPT_LANGUAGE, sanitized and all.
-* **preferred_language_from**:
+* **preferred_language_from(languages)**:
Finds the locale specifically requested by the browser
-* **compatible_language_from**:
+* **compatible_language_from(languages)**:
Returns the first of the user_preferred_languages that is compatible with the available locales.
Ignores region.
-* **sanitize_available_locales**:
+* **sanitize_available_locales(languages)**:
Returns a supplied list of available locals without any extra application info
that may be attached to the locale for storage in the application.
-* **language_region_compatible_from**:
+* **language_region_compatible_from(languages)**:
Returns the first of the user preferred languages that is
also found in available languages. Finds best fit by matching on
primary language first and secondarily on region. If no matching region is
found, return the first language in the group matching that primary language.
## Installation
-
### Without Bundler
Install the gem `http_accept_language`

0 comments on commit 8702c36

Please sign in to comment.