locale_setter 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in locale_setter.gemspec
+gemspec
+
+gem 'rspec'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jeff Casimir
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# LocaleSetter
+
+`LocaleSetter` sets the locale for the current request in a Rails application.
+
+## Installation
+
+### Gem Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'locale_setter'
+```
+
+Then execute:
+
+```
+$ bundle
+```
+
+### Application Configuration
+
+Include the module in your `app/controllers/application_controller.rb`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+
+  include LocaleSetter
+end
+```
+
+*Note:* If you have before filters or a module that handles user authentication, have that _above_ the `include LocaleSetter` so it happens first.
+
+## 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
+
+### 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. 
+
+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
+```
+
+If you're using a locale other than the default, then the parameter `locale` will be appended to every link.
+
+For example, my default is still `:en` but I'm currently reading in Spanish (`:es`):
+
+```
+http://example.com/articles/1&locale=es
+```
+
+You do not need to do any handling of this URL parameter, `LocaleSetter` will take care of it.
+
+If you *do* want to change the currently viewed locale, manipulate the URL parameter manually:
+
+Starting with the default...
+
+```
+http://example.com/articles/1
+```
+
+I want to check out German, so I add `&locale=de`...
+
+```
+http://example.com/articles/1&locale=de
+```
+
+Then check things out in Spanish...
+
+```
+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. 
+
+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.
+
+It's up to you to compute / store this data.
+
+#### Storing a User Preference
+
+The easiest solution is to add a column to your users table:
+
+```
+rails generate migration add_locale_to_users locale:string
+rake db:migrate
+```
+
+Then, allow them to edit this preference wherever they edit other profile items (email, name, etc). You might use a selector like this:
+
+```erb
+<%= form_for @user do |f| %>
+  <%= f.collection_select :locale, I18n.available_locales %>
+<% end %>
+```
+
+Remember that you may need to modify the `user.rb` if you're filtering mass-assignment parameters.
+
+### HTTP Headers
+
+Every request coming into your web server includes a ton of header information. One key/value pair looks like this:
+
+```
+HTTP_ACCEPT_LANGUAGE='en-US,en;0.8,es;0.4'
+```
+
+This string is created and sent by the user's browser. Most users have never configured it, the browser just picks it up from the host OS. It can usually be controlled through some kind of advanced preference pane.
+
+The sample string above means...
+
+* I prefer US English (`en-US`) for full comprehension
+* I will take general English (`en`) and will understand about 80% of the content
+* I will take general Spanish (`es`) and will understand about 40% of the content
+
+`LocaleSetter` will take care of processing this string and will use the highest-comprehension locale that your application supports.
+
+### Default
+
+Finally, if none of those previous options worked, the library will fall back to the currently specified `I18n.default_locale`.
+
+## Contributing
+
+This library is considered "experimental" quality. Your feedback would be very welcome! Pull requests are great, but issues are good too.
+
+### Test Application / Example Usage
+
+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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/locale_setter/http.rb

@@ -0,0 +1,19 @@
+module LocaleSetter
+  module HTTP
+    def self.for(accept_language)
+      LocaleSetter::Matcher.match(AcceptLanguageParser.parse(accept_language))
+    end
+
+    module AcceptLanguageParser
+      LOCALE_SEPARATOR = ','
+      WEIGHT_SEPARATOR = ';'
+
+      def self.parse(accept_language)
+        locale_fragments = accept_language.split(LOCALE_SEPARATOR)
+        weighted_fragments = locale_fragments.map{|f| f.split(WEIGHT_SEPARATOR)}
+        sorted_fragments = weighted_fragments.sort_by{|f| -f.last.to_f }
+        sorted_fragments.map{|locale, weight| locale}
+      end
+    end
+  end
+end

data/lib/locale_setter/matcher.rb

@@ -0,0 +1,24 @@
+module LocaleSetter
+  module Matcher
+    def self.match(requested, against = available)
+      matched = (sanitize(requested) & against).first
+      matched.to_sym if matched
+    end
+
+    def self.sanitize(input)
+      if input.respond_to? :map
+        input.map{|l| sanitize_one(l)}
+      else
+        [sanitize_one(input)]
+      end
+    end
+
+    def self.sanitize_one(locale)
+      locale.to_s.downcase.strip
+    end
+
+    def self.available
+      I18n.available_locales.map(&:to_s)
+    end
+  end
+end

data/lib/locale_setter/param.rb

@@ -0,0 +1,7 @@
+module LocaleSetter
+  module Param
+    def self.for(param)
+      LocaleSetter::Matcher.match([param])
+    end
+  end
+end

data/lib/locale_setter/rails.rb

@@ -0,0 +1,17 @@
+module LocaleSetter
+  module Rails
+    attr_accessor :i18n
+
+    def default_url_options(options = {})
+      if i18n.locale == i18n.default_locale
+        options
+      else
+        {:locale => i18n.locale}.merge(options)
+      end
+    end
+
+    def i18n
+      @i18n ||= I18n
+    end
+  end
+end

data/lib/locale_setter/user.rb

@@ -0,0 +1,9 @@
+module LocaleSetter
+  module User
+    def self.for(user)
+      if user && user.locale && !user.locale.empty?
+        LocaleSetter::Matcher.match(user.locale)
+      end
+    end
+  end
+end

data/lib/locale_setter/version.rb

@@ -0,0 +1,3 @@
+module LocaleSetter
+  VERSION = "0.1.0"
+end

data/lib/locale_setter.rb

@@ -0,0 +1,41 @@
+require "locale_setter/version"
+require "locale_setter/matcher"
+require "locale_setter/rails"
+require "locale_setter/http"
+require "locale_setter/user"
+require "locale_setter/param"
+
+module LocaleSetter
+  include LocaleSetter::Rails
+
+  def self.included(controller)
+    if controller.respond_to?(:before_filter)
+      controller.before_filter :set_locale
+    end
+  end
+
+  def set_locale
+    i18n.locale = from_params ||
+                  from_user   ||
+                  from_http   ||
+                  i18n.default_locale
+  end
+
+  def from_user
+    if respond_to?(:current_user) && current_user
+      LocaleSetter::User.for(current_user)
+    end
+  end
+
+  def from_http
+    if respond_to?(:request) && request.env && request.env['HTTP_ACCEPT_LANGUAGE']
+      LocaleSetter::HTTP.for(request.env['HTTP_ACCEPT_LANGUAGE'])
+    end
+  end
+
+  def from_params
+    if respond_to?(:params) && params[:locale]
+      LocaleSetter::Param.for(params[:locale])
+    end
+  end
+end

data/locale_setter.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'locale_setter/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "locale_setter"
+  gem.version       = LocaleSetter::VERSION
+  gem.authors       = ["Jeff Casimir"]
+  gem.email         = ["jeff@casimircreative.com"]
+  gem.description   = "Automatically set per-request locale in Rails applications"
+  gem.summary       = "Automatically set per-request locale in Rails applications"
+  gem.homepage      = "http://github.com/jcasimir/locale_setter"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/spec/locale/http_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+describe "LocaleSetter::HTTP" do
+  describe ".for" do
+    context "when the first choice is supported" do
+      before(:each){ I18n.available_locales = [:en, :es] }
+      
+      context "given 'en'" do
+        it "returns :en" do
+          LocaleSetter::HTTP.for("en").should == :en
+        end
+      end
+
+      context "given two acceptable locales" do
+        it "returns :en" do
+          LocaleSetter::HTTP.for("en,es").should == :en
+        end
+      end
+    end
+
+    context "when the first choice is not supported" do
+      before(:each){ I18n.available_locales = [:es] }
+      
+      context "given 'en,es'" do
+        it "returns :es" do
+          LocaleSetter::HTTP.for("en,es").should == :es
+        end
+      end
+    end
+
+    context "when using preference weightings" do
+      before(:each){ I18n.available_locales = [:en, :es] }
+
+      it "returns :en" do
+        LocaleSetter::HTTP.for("en;1,es;0.8").should == :en
+      end
+
+      it "handles misordered preferences" do
+        LocaleSetter::HTTP.for("es;0.8,en;1").should == :en
+      end
+    end
+  end
+end

data/spec/locale/matcher_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe "LocaleSetter::Matcher" do
+  it "can properly match mixed case locales" do
+    LocaleSetter::Matcher.match(['EN-US'],['en-us']).should == :'en-us'
+  end
+
+  it "can match using a single string" do
+    LocaleSetter::Matcher.match('en', ['en']).should == :en
+  end
+
+  it "can match using an array" do
+    LocaleSetter::Matcher.match(['en','es'],['en','es']).should == :en
+  end
+
+  it "can fuzzy-match between locales with country and those without"
+end

data/spec/locale/user_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe 'LocaleSetter::User' do
+  describe '#for' do
+    it "ignores a blank stored locale" do
+      blank = OpenStruct.new({:locale => ""})
+      LocaleSetter::User.for(blank).should_not be
+    end
+
+    it "ignores a stored locale that is not available" do
+      invalid = OpenStruct.new({:locale => "woof"})
+      LocaleSetter::User.for(invalid).should_not be
+    end
+
+    it "only tries current_user if it offers a locale" do
+      no_locale = OpenStruct.new()
+      LocaleSetter::User.for(no_locale).should_not be
+    end
+  end
+end

data/spec/locale_setter_spec.rb

@@ -0,0 +1,172 @@
+require 'spec_helper'
+
+describe LocaleSetter do
+  it "exists" do
+    expect{ LocaleSetter }.to_not raise_error
+  end
+
+  class BareController; end
+
+  describe ".included" do
+    it "sets a before filter" do
+      BareController.should_receive(:before_filter).with(:set_locale)
+      BareController.send(:include, LocaleSetter)
+    end
+
+    it "skips setting the before_filter if not supported" do
+      expect{ BareController.send(:include, LocaleSetter) }.to_not raise_error
+    end
+  end
+
+  class Controller
+    include LocaleSetter
+  end
+
+  let(:controller){ Controller.new }
+
+  describe "#default_url_options" do
+    it "adds a :locale key" do
+      controller.default_url_options({})[:locale].should be
+    end
+
+    it "does not require a parameter" do
+      expect{ controller.default_url_options }.to_not raise_error
+    end
+
+    it "builds on passed in options" do
+      result = controller.default_url_options({:test => true})
+      result[:test].should be
+      result[:locale].should be
+    end
+
+    it "defers to a passed in locale" do
+      result = controller.default_url_options({:locale => 'abc'})
+      result[:locale].should == 'abc'
+    end
+
+    it "doesn't appent a locale if it's the default" do
+      controller.i18n.locale = controller.i18n.default_locale
+      controller.default_url_options({})[:locale].should_not be
+    end
+
+    it "appends a locale when not the default" do
+      controller.i18n.locale = :sample
+      controller.default_url_options({})[:locale].should == :sample
+    end
+  end
+
+  describe "#set_locale" do
+    context "with nothing" do
+      let(:controller){ Controller.new }
+
+      it "uses the default" do
+        controller.set_locale
+        controller.i18n.locale.should == controller.i18n.default_locale
+      end
+    end
+
+    context "with HTTP headers" do
+      let(:controller){ HTTPController.new }
+
+      class HTTPController < Controller
+        def request
+          OpenStruct.new(:env => {'HTTP_ACCEPT_LANGUAGE' => "es,en"})
+        end
+      end
+
+      it "makes use of the HTTP headers" do
+        controller.set_locale
+        controller.i18n.locale.should == :es
+      end
+
+      it "only sets an available locale" do
+        I18n.available_locales = [:arr, :en]
+        controller.set_locale
+        controller.i18n.locale.should == :en
+      end
+
+      it "does nothing when HTTP_ACCEPT_LANGUAGE is missing" do
+        class BlankHTTPController < Controller
+          def request
+            OpenStruct.new(:env => {})
+          end
+        end
+        
+        blank = BlankHTTPController.new
+        blank.set_locale.should == blank.i18n.default_locale
+      end
+    end
+
+    context "with a current_user who has a locale" do
+      let(:controller){ UserController.new }  
+
+      before(:each) do
+        controller.i18n.available_locales = [:en, :user_specified]
+      end
+
+      class UserController < HTTPController
+        def current_user
+          OpenStruct.new({:locale => :user_specified})
+        end
+      end
+
+      it "prioritizes the current_user preference over HTTP" do
+        LocaleSetter::HTTP.should_not_receive(:for)
+        controller.set_locale
+      end
+
+      it "uses the stored locale" do
+        controller.set_locale
+        controller.i18n.locale.should == :user_specified
+      end
+    end
+
+    context "with url parameters" do
+      let(:controller){ ParamController.new }
+
+      before(:each) do
+        controller.i18n.available_locales = [:en, :param_specified]
+      end
+
+      class ParamController < Controller
+        def params
+          {:locale => "param_specified"}
+        end
+      end
+
+      it "uses the URL parameter" do
+        controller.set_locale
+        controller.i18n.locale.should == :param_specified
+      end
+
+      it "only allows supported locales" do
+        controller.i18n.available_locales = [:en]
+        controller.set_locale
+        controller.i18n.locale.should == controller.i18n.default_locale
+      end
+
+      it "does not pollute the symbol table when given an unsuported locale" do
+        class BadParamController < Controller
+          def params
+            {:locale => "bad_param"}
+          end
+        end
+        expect { BadParamController.new.set_locale }.to_not change{ Symbol.all_symbols.count }
+      end
+    end
+  end
+
+  describe "#i18n" do
+    it "uses the pre-set i18n library" do
+      stand_in = OpenStruct
+      controller.i18n = stand_in
+      controller.i18n.should == stand_in
+    end
+
+    class I18n; end
+
+    it "uses the default I18n library when not overridden" do
+      controller.i18n.should == I18n
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'bundler'
+Bundler.setup
+require 'locale_setter'
+require 'ostruct'
+require 'support/i18n'

data/spec/support/i18n.rb

@@ -0,0 +1,25 @@
+class I18n
+  def self.locale
+    @@locale ||= ""
+  end
+
+  def self.locale=(input)
+    @@locale = input
+  end
+
+  def self.available_locales
+    @@available_locales ||= []
+  end
+
+  def self.available_locales=(input)
+    @@available_locales = input
+  end
+
+  def self.default_locale
+    @@default_locale ||= :default
+  end
+
+  def self.default_locale=(input)
+    @@default_locale = input
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: locale_setter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jeff Casimir
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-20 00:00:00.000000000 Z
+dependencies: []
+description: Automatically set per-request locale in Rails applications
+email:
+- jeff@casimircreative.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/locale_setter.rb
+- lib/locale_setter/http.rb
+- lib/locale_setter/matcher.rb
+- lib/locale_setter/param.rb
+- lib/locale_setter/rails.rb
+- lib/locale_setter/user.rb
+- lib/locale_setter/version.rb
+- locale_setter.gemspec
+- spec/locale/http_spec.rb
+- spec/locale/matcher_spec.rb
+- spec/locale/user_spec.rb
+- spec/locale_setter_spec.rb
+- spec/spec_helper.rb
+- spec/support/i18n.rb
+homepage: http://github.com/jcasimir/locale_setter
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Automatically set per-request locale in Rails applications
+test_files:
+- spec/locale/http_spec.rb
+- spec/locale/matcher_spec.rb
+- spec/locale/user_spec.rb
+- spec/locale_setter_spec.rb
+- spec/spec_helper.rb
+- spec/support/i18n.rb