roda-i18n 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a3d6733ef6fdf42c06e7e28107e123ba746f0af
+  data.tar.gz: 517043eb03472e935a0ca625bd71cc07c53a8fe9
+SHA512:
+  metadata.gz: 33080f5390f7fea5ec9b4f6c85fb405cbaf70d0b8ce187eca20917ad83d61b071140deb5b03c04653a04f3fcb5f3d9816219f04a808a8ef3bec618e381e801b9
+  data.tar.gz: 1e96099edd2e3ecc6868b67982edb185a9ce9ed5cf5cb9dacb0d63c1f12e52fc3328653a3320b775189ceeef3d26f0341204b05ca9607d2d4c1a4c00603c93cd

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2015 Kematzy
+
+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 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,309 @@
+# Roda-i18n
+
+Easily add Internationalisation (i18n) and localisation support for [Roda](http://roda.jeremyevans.net/) apps, based upon the [R18n](https://github.com/ai/r18n) gem.
+
+Extensively tested and with 100% code test coverage.
+
+
+## Installation
+
+To use this gem, just do
+
+    $ (sudo) gem install roda-i18n
+    
+or if you use Bundler
+
+    gem "roda-i18n"
+
+
+<br>
+
+
+## Getting Started
+
+To add internationalisation and localisation support to your app just add the following code snippet in your app.
+
+    plugin :i18n
+
+By default the default locale is set to <tt>'en'</tt> and the translations directory is set to the <tt>'i18n'</tt> directory in the rooot of your app, ie: '<tt>/path/2/app/i18n</tt>'.
+
+
+**IMPORTANT! Make sure you create the 'i18n' folder and add an 'en.yml' file with 
+at least one translation within it.**
+
+
+<br>
+
+
+## Configuration
+
+### Overriding defaults during configuration
+
+Both <tt>:locale</tt> and <tt>:translations</tt> can be configured (overridden) during plugin configuration:
+
+    plugin :i18n, :locale => ['de'], :translations => ['absolute/path/2/i18n']
+
+
+**NOTE!** 
+
+ 1. You must set <tt>opts[:root]</tt> in your app if you do not define the <tt>:translations</tt> path during plugin configuration.
+
+ 2. When overriding <tt>:translations</tt> the **any path(s) given must be absolute**.
+
+
+#### Loading translations from multiple i18n directories
+
+The <tt>:translations</tt> path supports 'wildcards', ie: <tt>path/**/i18n</tt> so you can load translations from multiple combined apps, each with their own <tt>i18n</tt> folder with translations.
+
+**Please Note!** 
+
+When loading translations from multiple sources and the same translation key is available in multiple files of the same locale, then **the translations in the first loaded translation file takes precedence over subsequent loaded translations**. 
+
+* ie: translations in <tt>./i18n/en.yml</tt> takes precedence over translations in <tt>./apps/app1/i18n/en.yml</tt>
+
+
+You can also set a list of preferred locales as an array ordered by priority.
+
+    plugin :i18n, :locale => ['es','fr','en']
+
+
+
+<br>
+
+
+##  USAGE
+
+The **i18n** plugin depends upon simple YAML based translations files:
+
+    # app/i18n/en.yml
+    
+    user:
+      edit: Edit user
+      name: User name is %1
+      count: !!pl
+        1: There is 1 user
+        n: There are %1 users
+    
+
+...and the **<tt>:t</tt>** instance method to output the translations:
+
+    
+    t.user.edit         #=> "Edit user"
+    t.user.name('John') #=> "User name is John"
+    t.user.count(5)     #=> "There are 5 users"
+    
+    t.does.not.exist | 'default' #=> "default"
+    
+
+...and the **<tt>:l</tt>** (lowercase L) instance method provides built-in localisations support:
+
+    
+    l Time.now           #=> "03/01/2010 18:54"
+    l Time.now, :human   #=> "now"
+    l Time.now, :full    #=> "3rd of January, 2010 18:54"
+    
+
+
+Both the <tt>:t</tt> and <tt>:l</tt> methods are available within the route and template (erb) scopes. ie:
+
+    
+    route do |r|
+      r.root do
+        t.welcome.message
+      end
+    end
+    
+    # app/views/layout.erb
+    <snip...>
+      <h1><%= t.welcome.message %></h1>
+    <snip...>
+    
+
+
+Please visit [R18n](https://github.com/ai/r18n/tree/master/r18n-core) for more information about the R18n gem used to create the above.
+
+<br>
+
+## Key Methods / Functionality
+
+
+<br>
+
+
+### <tt>#locale(opts={},&blk)</tt> - (request method)
+
+This request method makes it easy to handle translations based upon the **<tt>:locale</tt> prefix on a route / URL**. ie: <tt>blog.com/**de**/posts</tt>.
+
+
+To enable this, just use the following code structure:
+
+    route do |r|
+      
+      # all routes are prefixed with '/:locale'
+      # ie: GET /de/posts  => will use DE translations    
+      # ie: GET /es/posts  => will use ES translations
+      
+      r.locale do          # also aliased as #i18n_locale
+        r.is 'posts' do 
+	      t.posts.header # use translations or locales
+        end
+      end
+      
+    end
+    
+
+	
+
+**NOTE!** Any URL / request with a non-present or not supported locale will be given the **configured default locale** or the EN (English) default locale.
+
+
+<br>
+
+
+### <tt>#i18n_set_locale_from(type)</tt> - (request method)
+
+Obtains the locale from either ENV, HTTP (browser), Params or Session values.
+
+    route do |r|
+      # A): set from session[:locale] (if present)
+      r.i18n_set_locale_from(:session)
+      
+      # B): set from URL params ie: GET /posts?locale=de
+      r.i18n_set_locale_from(:params)
+      
+      # C): set from the browser's HTTP request locale
+      r.i18n_set_locale_from(:http)
+      
+      # D): set from the server ENV['LANG'] variable
+      r.i18n_set_locale_from(:ENV)
+      
+      
+      r.is 'posts' do 
+        t.posts.header # use translations
+      end
+    end
+
+
+**NOTE!** defaults to the configured default locale, or English, if the given locale type is invalid.
+
+
+<br>
+
+
+### <tt>#i18n_set_locale(locale, &blk)</tt> - (request method)
+
+Enables overriding the default locale and setting a temporary :locale
+within a route block.
+  
+    route do |r|
+      # configured default locale
+      
+	   <snip...>
+	   
+      r.i18n_set_locale('de') do
+        # within this route block the locale is DE (German)
+      end
+      
+      r.i18n_set_locale('es') do
+        # within this route block the locale is ES (Spanish)
+      end
+    
+    end
+  
+
+
+
+      
+## InstanceMethods
+
+### `#t`
+
+This is the main translation output method. (See examples above)
+
+
+<br>
+
+
+### `#l`
+
+Key localisation method. Handles dates etc. (See examples above)
+
+
+<br>
+
+
+### `#i18n_available_locales`
+
+Returns a two-dimensional array of available locales.
+
+    puts i18n_available_locales #=> [ ['en', 'English'], ...]
+
+
+
+        
+### `#i18n_default_places`
+
+
+<br>
+
+
+## Class Methods
+        
+### <tt>#i18n_opts</tt>
+
+Return the i18n options for this class as a Hash.
+
+
+<br>
+
+
+## Ideas
+
+A few ideas that may be outlandish, but possible?
+
+
+### Ability to load translations from multiple locations via an array.
+
+    plugin :i18n, :translations => ['app1/i18n', 'app2/i18n', 'app3/i18n']
+
+
+> [Concept Reference](https://github.com/ai/r18n/tree/master/r18n-core#loaders)
+>    
+> You can also set several loaders to merge translations from different sources:
+>    
+>     R18n.default_places = [MyLoader.new, DBLoader.new, 'path/to/yaml']
+>    
+
+
+### Sequel DBLoader for DB based translations support
+
+Som form of built-in support for storing / loading translations from a Sequel based DB.
+
+
+<br>
+
+
+----
+
+## TODOs
+
+* I'm sure there's something, but right now the list is empty ;-)
+
+
+## Credits
+
+* This plugin have been inspired by the `sinatra-i18n` gem available at [github/ai/r18n](http://github.com/ai/r18n) created by [Andrey Sitnik](http://github.com/ai).
+
+* Testing code have been partly copied from [Forme](github.com/jeremyevans/forme).
+
+* Inspiration and assistance by [Jeremy Evans](github.com/jeremyevans). Many thanks Jeremy!! 
+
+
+## Licence
+
+MIT 
+
+Copyright: 2015 Kematzy 
+
+
+

data/Rakefile

@@ -0,0 +1,78 @@
+require "rake"
+require "rake/clean"
+
+NAME = 'roda-i18n'
+CLEAN.include ["#{NAME}-*.gem", "rdoc", "coverage", '**/*.rbc']
+
+# Gem Packaging and Release
+
+desc "Packages #{NAME}"
+task :package=>[:clean] do |p|
+  sh %{gem build #{NAME}.gemspec}
+end
+
+desc "Upload #{NAME} gem to rubygems"
+task :release=>[:package] do
+  sh %{gem push ./#{NAME}-#{VERS.call}.gem} 
+end
+
+# ### RDoc
+#
+# RDOC_DEFAULT_OPTS = ["--line-numbers", "--inline-source", '--title', 'Roda I18n']
+#
+# begin
+#   gem 'hanna-nouveau'
+#   RDOC_DEFAULT_OPTS.concat(['-f', 'hanna'])
+# rescue Gem::LoadError
+# end
+#
+# rdoc_task_class = begin
+#   require "rdoc/task"
+#   RDoc::Task
+# rescue LoadError
+#   require "rake/rdoctask"
+#   Rake::RDocTask
+# end
+#
+# RDOC_OPTS = RDOC_DEFAULT_OPTS + ['--main', 'README.rdoc']
+#
+# rdoc_task_class.new do |rdoc|
+#   rdoc.rdoc_dir = "rdoc"
+#   rdoc.options += RDOC_OPTS
+#   rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/**/*.rb"
+# end
+
+### Specs
+
+desc "Run specs"
+task :spec do
+  sh "#{FileUtils::RUBY} -rubygems -I lib -e 'ARGV.each{|f| require f}' ./spec/*_spec.rb"
+end
+task :default => :spec
+
+desc "Run specs with coverage"
+task :coverage do
+  ENV['COVERAGE'] = '1'
+  Rake::Task['spec'].invoke
+end
+
+### Other
+
+# desc "Print #{NAME} version"
+# task :version do
+#   puts VERS.call
+# end
+
+desc "Check syntax of all .rb files"
+task :check_syntax do
+  Dir['**/*.rb'].each{|file| print `#{ENV['RUBY'] || :ruby} -c #{file} | fgrep -v "Syntax OK"`}
+end
+
+# desc "Start an IRB shell using the extension"
+# task :irb do
+#   require 'rbconfig'
+#   ruby = ENV['RUBY'] || File.join(RbConfig::CONFIG['bindir'], RbConfig::CONFIG['ruby_install_name'])
+#   irb = ENV['IRB'] || File.join(RbConfig::CONFIG['bindir'], File.basename(ruby).sub('ruby', 'irb'))
+#   sh %{#{irb} -I lib -r forme}
+# end
+

data/lib/roda/plugins/i18n.rb

@@ -0,0 +1,276 @@
+require 'r18n-core'
+
+class Roda
+  module RodaPlugins
+    # The i18n plugin allows you to easily add internationalisation (i18n) and
+    # localisation support to your Roda app, by adding the following:
+    # 
+    #    plugin :i18n
+    # 
+    # By default the default locale is set to <tt>'en'</tt> and the translations directory 
+    # is set to <tt>'i18n'</tt> in the rooot of your app.
+    # 
+    # Both <tt>:locale</tt> and <tt>:translations</tt> can be overridden during configuration:
+    #    
+    #    plugin :i18n, :locale => ['de'], :translations => ['absolute/path/2/i18n']
+    # 
+    # Please note! 
+    #  1) You must set <tt>opts[:root]</tt> in your app if you don't define the <tt>:translations</tt> path.
+    #  
+    # 2) When overriding <tt>:translations</tt> the path given must be absolute.
+    # 
+    # The path supports 'wildcards', ie: path/**/i18n so you can load translations from multiple
+    # combined apps each with their own <tt>i18n</tt> folder with translations.
+    # 
+    # Note! when loading translations from multiple sources and the same translation key is used 
+    # in both files, the first loaded file takes precedence, ie: <tt>./i18n/en.yml</tt> takes precedence over
+    # <tt>./apps/app1/i18n/en.yml</tt>
+    # 
+    # == USAGE
+    # 
+    # The i18n plugin depends upon simple YAML based translations files:
+    # 
+    #     # app/i18n/en.yml
+    #     
+    #     user:
+    #       edit: Edit user
+    #       name: User name is %1
+    #       count: !!pl
+    #         1: There is 1 user
+    #         n: There are %1 users
+    #     
+    # 
+    # and the <tt>:t</tt> instance method to output the translations:
+    # 
+    #     
+    #     t.user.edit         #=> "Edit user"
+    #     t.user.name('John') #=> "User name is John"
+    #     t.user.count(5)     #=> "There are 5 users"
+    #     
+    #     t.does.not.exist | 'default' #=> "default"
+    #     
+    #  
+    # the <tt>:l</tt> instance method provides built-in localisations support:
+    # 
+    #      l Time.now           #=> "03/01/2010 18:54"
+    #      l Time.now, :human   #=> "now"
+    #      l Time.now, :full    #=> "3rd of January, 2010 18:54"
+    #   
+    # Both the <tt>:t</tt> and <tt>:l</tt> methods are available in the route and template (erb) scopes. ie:
+    # 
+    #     route do |r|
+    #       r.root do
+    #         t.welcome.message
+    #       end
+    #     end
+    #     
+    #     # app/views/layout.erb
+    #     <snip...>
+    #       <h1><%= t.welcome.message %></h1>
+    #     <snip...>
+    #     
+    # 
+    # 
+    # Visit [R18n](https://github.com/ai/r18n/tree/master/r18n-core) for more information.
+    # 
+    # 
+    # The i18n plugin also makes it easy to handle locales:
+    # 
+    # 
+    # === <tt>:locale</tt> RequestMethod
+    # 
+    # This request method makes it to handle translations based upon the :locale prefix on a URL,
+    #  ie: <tt>blog.com/de/posts</tt>, just use the following code:
+    # 
+    #     route do |r|
+    #       
+    #       r.locale do
+    #         r.is 'posts' do 
+    #           t.posts.header
+    #         end
+    #       end
+    #       
+    #     end
+    # 
+    # 
+    # === <tt>:i18n_set_locale_from</tt> RequestMethod
+    # 
+    # Obtains the locale from either ENV, HTTP (browser), Params or Session
+    # values
+    # 
+    # 
+    # Naturally we can allow browsers to override the default locale within routes, like this:
+    # 
+    #     route do |r|
+    #       i18n_set_locale_from(:http)  #=> set to the browser's default locale (en-US)
+    #       r.get '' do
+    #         t.hello  #=> 'Howdy, I speak American English'
+    #       end
+    #     end
+    # 
+    # The def
+    # 
+    # 
+    #     route do |r|
+    #       i18n_set_locale('de')
+    #       r.get 'in-german' do
+    #         t.hello  #=> 'Guten tag, ich spreche deutsch'
+    #       end
+    #     end
+    # 
+    # 
+    # 
+    # 
+    module RodaI18n
+      
+      def self.load_dependencies(app, opts={})
+        # app.plugin :render
+        # app.plugin :environments
+      end
+      
+      def self.configure(app, opts={})
+        opts = app.opts[:i18n][:orig_opts].merge(opts) if app.opts[:i18n]
+        app.opts[:i18n] = opts.dup
+        app.opts[:i18n][:orig_opts] = opts
+        opts = app.opts[:i18n]
+        
+        ::R18n.default_places = opts[:translations] || File.expand_path('i18n', app.opts[:root])
+        
+        opts[:default_locale] = opts[:locale].is_a?(Array) ? opts[:locale].first : opts[:locale] || 'en'
+        ::R18n::I18n.default = opts[:default_locale]
+        
+        ::R18n.clear_cache! if ENV['RACK_ENV'] != 'production'
+        i18n   = R18n::I18n.new(opts[:locale], ::R18n.default_places,
+                                  off_filters: :untranslated,
+                                  on_filters:  :untranslated_html)
+        ::R18n.set(i18n)
+      end
+      
+      
+      module RequestMethods
+        
+        # Obtains the locale from either ENV, HTTP (browser), Params or Session
+        # values.
+        # 
+        #   route do |r|
+        #     # A): set from URL params ie: GET /posts?locale=de
+        #     r.i18n_set_locale_from(:params)
+        #     
+        #     # B): set from session[:locale] (if present)
+        #     r.i18n_set_locale_from(:session)
+        #     
+        #     # C): set from the browser's HTTP request locale
+        #     r.i18n_set_locale_from(:http)
+        #     
+        #     # D): set from the server ENV['LANG'] variable
+        #     r.i18n_set_locale_from(:ENV)
+        #     
+        #     
+        #     r.is 'posts' do 
+        #       t.posts.header # use translations
+        #     end
+        #   end
+        # 
+        def i18n_set_locale_from(type)
+          case type.to_sym
+          when :http
+            _locale = ::R18n::I18n.parse_http(scope.request.env['HTTP_ACCEPT_LANGUAGE'])
+          when :session
+            _locale = session[:locale] if session[:locale]
+          when :params
+            _locale = scope.request.params['locale'] if scope.request.params['locale']
+          when :ENV
+            _locale = ENV['LANG'].split('.').first if ENV['LANG']
+          else
+            _locale = nil
+          end
+          # sanity check: set to default locale if not set above
+          _locale = ::R18n::I18n.default.to_s if _locale.nil?
+          
+          _i18n = ::R18n::I18n.new(_locale, ::R18n.default_places,
+                                    off_filters: :untranslated, 
+                                    on_filters: :untranslated_html)
+          ::R18n.set(_i18n)
+        end
+        
+        # Enables setting temporary :locale.
+        # 
+        #   route do |r|
+        #     
+        #     r.i18n_set_locale('de') do
+        #       # within this block the locale is DE (German)
+        #     end
+        #     
+        #     r.i18n_set_locale('es') do
+        #       # within this block the locale is ES (Spanish)
+        #     end
+        #     
+        #   end
+        # 
+        def i18n_set_locale(locale, &blk)
+          locale = ::R18n::I18n.default.to_s if locale.nil?
+          
+          _i18n = ::R18n::I18n.new(locale, ::R18n.default_places,
+                                    off_filters: :untranslated, 
+                                    on_filters: :untranslated_html)
+          ::R18n.set(_i18n)
+          yield
+        end
+        
+        # Sets the locale based upon <tt>:locale</tt> prefixed routes
+        #  
+        #   route do |r|
+        #     r.locale do
+        #       # all routes are prefixed with '/:locale'
+        #       # ie: GET /de/posts  => will use DE translations
+        #       # ie: GET /es/posts  => will use ES translations
+        #       r.is 'posts' do 
+        #         t.posts.header # use translations or locales
+        #       end
+        #     end
+        #   end
+        #
+        def locale(opts={}, &blk)
+          on(':locale', opts) do |l|
+            _locale = l || self.class.opts[:locale]
+            session[:locale] = _locale unless session[:locale]
+            ::R18n.set(_locale)
+            yield
+          end
+        end
+        alias_method :i18n_locale, :locale
+      
+      
+      end #/module RequestMethods
+      
+      module ClassMethods
+        
+        # Return the i18n options for this class.
+        def i18n_opts
+          opts[:i18n]
+        end
+        
+      end #/module ClassMethods
+      
+      module InstanceMethods
+        include ::R18n::Helpers
+        
+        def i18n_available_locales
+          @available_locales = []
+          ::R18n.available_locales.each do |l|
+            @available_locales << [l.code, l.title]
+          end
+          @available_locales
+        end
+        
+        def i18n_default_places
+          ::R18n.default_places
+        end
+        
+      end
+      
+    end #/module RodaI18n
+    
+    register_plugin(:i18n, RodaI18n)
+  end #/module RodaPlugins
+end #/class Roda