tr8n_client_sdk 3.2.2 → 3.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9802bfd002589491b5e71c353cad0372d5d251c1
-  data.tar.gz: c073f2d7078cc2183cf7178c46f1b113d33d9e29
+  metadata.gz: b1f8b6538d43509ecfd11b6153371c54e153eca5
+  data.tar.gz: 32beb12f88d7dd8b16ea9e66dbb4f882f1d5b9f1
 SHA512:
-  metadata.gz: 21979fba2779078034813c6ebf2a0ff746c97a497bffc53962e0ac9a4ecf6ad697e28cbe9d53d4f996b584a145dec53a60a5371fe7534c0c09dbe78ff930e5f5
-  data.tar.gz: 62eb86e095c80117194b1b54990d014262892b77fdaf54e9a99af5a1fd72397c452f82c28d1b1386ae99b4e1a0004b3c7a3cdf057cf73e1af7d38de43d7ce353
+  metadata.gz: aadb32a0a3610db0859c5cb049dba6b1d3844986ec5985f789dba37f8c68bd28e811f8d1315860bb4f478ae939e502288ad406a5fbe2c69eb1a1c3bcb5a8966a
+  data.tar.gz: 4af105edf554a27952a0079545b020aa2544716a3ac948dbbe5a05e2197fbd740e1b2ceacf5b0fa2916df3c513b1cc9ec55c977c5bbe62724bb2c5c82eed7912

data/README.md

@@ -4,49 +4,60 @@
 
 Tr8n Client SDK for Ruby on Rails
 ===================================
-
-This Client SDK provides tools and extensions necessary for translating any Rails application using the Tr8n service.
-
-[![Build Status](https://travis-ci.org/tr8n/tr8n_rails_clientsdk.png?branch=master)](https://travis-ci.org/tr8n/tr8n_rails_clientsdk)
+[![Build Status](https://travis-ci.org/tr8n/tr8n_rails_clientsdk.png?branch=rails-3.2.x)](https://travis-ci.org/tr8n/tr8n_rails_clientsdk)
 [![Coverage Status](https://coveralls.io/repos/tr8n/tr8n_rails_clientsdk/badge.png)](https://coveralls.io/r/tr8n/tr8n_rails_clientsdk)
 [![Gem Version](https://badge.fury.io/rb/tr8n_client_sdk.png)](http://badge.fury.io/rb/tr8n_client_sdk)
-[![Dependency Status](https://www.versioneye.com/user/projects/52e4bc4cec1375b57600000f/badge.png)](https://www.versioneye.com/user/projects/52e4bc4cec1375b57600000f)
+[![Dependency Status](https://www.versioneye.com/user/projects/53cda6a5225426f1e8000165/badge.svg?style=flat)](https://www.versioneye.com/user/projects/53cda6a5225426f1e8000165)
 [![Project status](http://stillmaintained.com/tr8n/tr8n_ruby_core.png)](http://stillmaintained.com/tr8n/tr8n_ruby_core.png)
 
+This Client SDK provides extensions necessary for translating Rails 3.2.X based application using the TranslationExchange.com service.
+
 
-Runing the Client SDK Sample
+Tr8n Client SDK Sample
 ===================================
 
+The best way to start using the SDK is to run a sample application that comes bundled with this SDK.
 
-To run the gem as a stand-alone application follow these:
+```sh
+  $ git clone https://github.com/tr8n/tr8n_rails_clientsdk.git
+  $ cd tr8n_rails_clientsdk/spec/dummy
+  $ bundle
+```
+
+Before you running the application, visit TranslationExchange.com, register as a new user and create a new application.
+
+Update your key and secret in the following file:  config/initializers/tr8n.rb
+
+```ruby
+  config.application = {
+      :key => YOUR_KEY,
+      :secret => YOUR_SECRET
+  }
+```
 
-Make sure you edit the config/tr8n/config.yml file and provide the correct application host, key and secret for your application.
+Now you can start the application by running:
 
 ```sh
-  $ git clone https://github.com/tr8n/tr8n_rails_clientsdk.git
-  $ cd tr8n_rails_clientsdk/test/dummy
-  $ bundle install
-  $ rake db:migrate
-  $ rails s
+  $ bundle exec rails s
 ```
 
-Alternatively, you can see the same sample application as a stand alone app:
 
-https://github.com/tr8n/tr8n_rails_clientsdk_sample
+This will start the dummy application on port 3000. Open your browser and point to:
+
+http://localhost:3000
 
-This application is running at:
 
-http://rails.tr8nhub.com
 
-# Integration Instructions
 
-Here are a few points on how to integrate Tr8n into your app:
+Integration
+===================================
+
+To integrate Tr8n SDK into your own app, all you need to do is:
 
-Add the following gems to your Gemfile:
+Add the following gem to your Gemfile:
 
 ```ruby
-  gem 'tr8n_core'
-  gem 'tr8n_client_sdk'
+  gem 'tr8n_client_sdk', '~> 3.2'
 ```
 
 Install the gems:
@@ -55,21 +66,50 @@ Install the gems:
   $ bundle
 ```
 
-Generate config file:
+Create an initializer file under config/initializers/tr8n.rb and add the following configuration:
 
-```sh
-  $ rails g tr8n_client_sdk
+```ruby
+    Tr8n.configure do |config|
+      config.application = {
+          :key => YOUR_APP_KEY,
+          :secret => YOUR_APP_SECRET
+      }
+    end
 ```
 
-Open the config file and provide your application credentials:
+Tr8n is best run with caching enabled. You can specify your caching adapter using the following settings:
+
+Memcache example:
 
+```ruby
+    Tr8n.configure do |config|
+      config.cache = {
+          :enabled  => true,
+          :adapter  => 'memcache',
+          :host     => 'localhost:11211',
+          :version  => 1,
+          :timeout  => 3600
+      }
+    end
 ```
-  application:
-    host:         http://localhost:3000
-    key:          YOUR_APP_KEY
-    secret:       YOUR_APP_SECRET
+
+Redis example:
+
+```ruby
+    Tr8n.configure do |config|
+      config.cache = {
+          :enabled  => true,
+          :adapter  => 'redis',
+          :host     => 'localhost:6379',
+          :version  => 1,
+          :timeout  => 3600
+      }
+    end
 ```
 
+To see a full list of supported cache adapters or to create your own cache adapter, visit TranslationExchange.com/docs
+
+
 In the HEAD section of your layout, add:
 
 ```ruby
@@ -78,6 +118,129 @@ In the HEAD section of your layout, add:
 
 You are done, tr8n is now running in your app.
 
-To read more about what you can do with it, visit the wiki site:
+Now you can simply add the default language selector anywhere on your page using:
+
+```ruby
+  <%= tr8n_language_selector_tag %>
+```
+
+And use TML (Translation Markup Language) to translate your strings, using:
+
+```rails
+  <%= tr("Hello World") %>
+  <%= tr("You have {count||message}", :count => 5) %>
+  <%= tr("{actor} sent {target} [bold: {count||gift}]", :actor => actor_user, :target => target_user, :count => 5) %>
+  ...
+```
+
+Learn more about TML at: https://TranslationExchange.com/docs
+
+
+Caching
+===================================
+
+To reset/upgrade your cache, you can simply call
+
+```ruby
+  Tr8n.cache.upgrade_version
+```
+
+All the keys stored in memory based cache are versioned. By upgrading the version you will effectively invalidate the old keys and the new keys will be loaded from the translation service.
+
+
+File adapters require pre-generation. You can pre-generate your cache by running:
+
+```sh
+  $ rake tr8n:generate_cache:cdb
+```
+
+You can also do a combination of file-based adapters (for persistent cache) and memory-based adapters for serving the translations.
+
+
+Logging
+===================================
+
+Tr8n comes with its own logger. If you would like to see what the SDK is doing behind the scene, enable the logger and provide the file path for the log file:
+
+```ruby
+    Tr8n.configure do |config|
+
+      config.logger  = {
+          :enabled  => true,
+          :path     => "#{Rails.root}/log/tr8n.log",
+          :level    => 'debug'
+      }
+
+    end
+```
+
+
+Customization
+===================================
+
+Tr8n comes with default settings for the rules engine. For example, it assumes that you have the following methods in your ApplicationController:
+
+```ruby
+  def current_user
+  end
+
+  def current_locale
+  end
+```
+
+Tr8n only needs the current_user method if your site needs to use gender based rules for the viewing user.
+
+Similarly, if you prefer to use your own mechanism for storing and retrieving user's preferred and selected locales, you can provide the current_locale method.
+
+If you need to adjust those method names, you can set them in the config:
+
+```ruby
+    Tr8n.configure do |config|
+
+      config.current_user_method = :my_user
+
+      config.current_locale_method = :my_locale
+
+    end
+```
+
+
+Links
+==================
+
+* Register on TranslationExchange.com: https://translationexchange.com
+
+* Read TranslationExchange's documentation: http://wiki.translationexchange.com
+
+* Visit TranslationExchange's blog: http://blog.translationexchange.com
+
+* Follow TranslationExchange on Twitter: https://twitter.com/translationx
+
+* Connect with TranslationExchange on Facebook: https://www.facebook.com/translationexchange
+
+* If you have any questions or suggestions, contact us: info@translationexchange.com
+
+
+Copyright and license
+==================
+
+Copyright (c) 2014 Michael Berkovich, TranslationExchange.com
+
+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.
 
-http://wiki.tr8nhub.com
+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/app/views/tr8n_client_sdk/tags/_language_selector.html.erb

@@ -1,5 +1,53 @@
-<a href="#" onClick="Tr8n.UI.LanguageSelector.show(); return false;">
-  <%= image_tag(tr8n_current_language.flag_url, :style => "align:middle") %>
-  &nbsp;
-  <%= tr8n_current_language.name %>
-</a>
+<% if opts[:type] == :dropdown %>
+  <script>
+    function tr8n_change_locale(selector) {
+      var query_parts = window.location.href.split('?');
+      var query = query_parts.length > 1 ? query_parts[1] : null;
+      var params = {};
+      if (query) {
+        var vars = query.split('&');
+        for (var i = 0; i < vars.length; i++) {
+          var pair = vars[i].split('=');
+          params[pair[0]] = pair[1];
+        }
+      }
+      params['locale'] = selector.options[selector.selectedIndex].value;
+
+      query = [];
+      var keys = Object.keys(params);
+      for (var i = 0; i < keys.length; i++) {
+        query.push(encodeURIComponent(keys[i]) + "=" + encodeURIComponent(params[keys[i]]));
+      }
+
+      var destination = query_parts[0] + '?' + query.join("&");
+      window.location = destination;
+    }
+  </script>
+  <select id="tr8n_language_selector" onchange="tr8n_change_locale(this)" style="<%=opts[:style]%>" class="<%=opts[:class]%>">
+    <% tr8n_application.languages.each do |lang| %>
+      <option value="<%=lang.locale%>" <%="selected" if lang.locale == tr8n_current_locale %>>
+        <% if opts[:language] == :native %>
+          <%= lang.native_name %>
+        <% elsif opts[:language] == :english %>
+          <%= lang.english_name %>
+        <% else %>
+          <%= lang.name %>
+        <% end %>
+      </option>
+    <% end %>
+  </select>
+<% else %>
+  <a href="#" onClick="Tr8n.UI.LanguageSelector.show(); return false;">
+    <% unless opts[:hide_flag] %>
+      <%= image_tag(tr8n_current_language.flag_url, :style => "align:middle") %>
+      &nbsp;
+    <% end %>
+    <% if opts[:language] == :native %>
+      <%= tr8n_current_language.native_name %>
+    <% elsif opts[:language] == :english %>
+      <%= tr8n_current_language.english_name %>
+    <% else %>
+      <%= tr8n_current_language.name %>
+    <% end %>
+  </a>
+<% end %>

data/lib/tr8n_client_sdk/extensions/action_controller_extension.rb

@@ -37,6 +37,13 @@ module Tr8nClientSdk
       base.send(:include, InstanceMethods)
       base.before_filter :tr8n_init_client_sdk
       base.after_filter :tr8n_reset_client_sdk
+      if defined? base.rescue_from
+        base.rescue_from 'Tr8n::Exception' do |e|
+          Tr8n.logger.error(e)
+          Tr8n.logger.error(e.backtrace)
+          raise e
+        end
+      end
     end
 
     module InstanceMethods
@@ -65,20 +72,55 @@ module Tr8nClientSdk
         nil
       end
 
+      def tr8n_cookie_name
+        "tr8n_#{tr8n_application.key}"
+      end
+
+      def tr8n_cookie
+        request.cookies[tr8n_cookie_name]
+      end
+
+      def tr8n_cookie_params
+        @tr8n_cookie_params ||= begin
+          if tr8n_cookie
+            cookie_params = Tr8n::Utils.decode_and_verify_params(tr8n_cookie, tr8n_application.secret)
+            Tr8n.logger.info(cookie_params.inspect)
+            cookie_params
+          else
+            {}
+          end
+        end
+      end
+
+      def tr8n_translator_locale
+        tr8n_cookie_params["locale"]
+      end
+
       def tr8n_init_current_locale
         self.send(Tr8n.config.current_locale_method) if Tr8n.config.current_locale_method
       rescue
+        # fallback onto the cookie params from the service
+        return tr8n_translator_locale if tr8n_translator_locale
+
         # fallback to the default session based locale implementation
         # choose the first language from the accepted languages header
         session[:locale] = tr8n_user_preferred_locale unless session[:locale]
         session[:locale] = params[:locale] if params[:locale]
-        session[:locale]
+        session[:locale] || Tr8n.config.default_locale
       end
 
       def tr8n_init_current_user
         self.send(Tr8n.config.current_user_method) if Tr8n.config.current_user_method
       rescue
-        Tr8n.config.default_locale
+        nil
+      end
+
+      def tr8n_init_current_translator
+        if tr8n_cookie_params["translator"]
+          Tr8n::Translator.new(tr8n_cookie_params["translator"].merge(:application => tr8n_application))
+        else
+          nil
+        end
       end
 
       def tr8n_init_client_sdk
@@ -88,21 +130,10 @@ module Tr8nClientSdk
 
         return unless Tr8n.session.init
 
-        translator = nil
-
-        cookie_name = "tr8n_#{tr8n_application.key}"
-        if request.cookies[cookie_name]
-          cookie_params = Tr8n::Utils.decode_and_verify_params(request.cookies[cookie_name], tr8n_application.secret)
-          Tr8n.logger.info(cookie_params.inspect)
-          locale = cookie_params["locale"]
-          translator = Tr8n::Translator.new(cookie_params["translator"].merge(:application => tr8n_application)) unless cookie_params["translator"].nil?
-        end
-
-        locale ||= tr8n_init_current_locale || Tr8n.config.default_locale
-
         Tr8n.session.current_user = tr8n_init_current_user
-        Tr8n.session.current_translator = translator
-        Tr8n.session.current_language = tr8n_application.language(locale || tr8n_init_current_locale || Tr8n.config.default_locale)
+        Tr8n.session.current_language = tr8n_application.language(tr8n_init_current_locale)
+        Tr8n.session.current_translator = tr8n_init_current_translator
+
         Tr8n.session.current_source = tr8n_source
         Tr8n.session.current_component = tr8n_component
       end

data/lib/tr8n_client_sdk/version.rb

@@ -22,5 +22,5 @@
 #++
 
 module Tr8nClientSdk
-  VERSION = "3.2.2"
+  VERSION = "3.2.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tr8n_client_sdk
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 3.2.3
 platform: ruby
 authors:
 - Michael Berkovich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-25 00:00:00.000000000 Z
+date: 2014-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails