splendeo_translator 1.0.0

data/README.rdoc

@@ -0,0 +1,163 @@
+= SplendeoSplendeoTranslator - i18n tooling for Rails
+
+SplendeoTranslator makes using the internationalization (i18n) facility introduced in Rails 2.2 simpler through:
+* keeping your code DRY using simple conventions
+* make testing easier to catch missing keys
+* supplying a graceful "fallback" mode when a translation is missing in a user's locale
+
+== The Problem
+
+The (very!) helpful I18n[http://api.rubyonrails.org/classes/I18n.html] library finds keys in locale bundles (and more), but doesn't know anything about Rails applications. Applications that have a lot of strings need a system of keeping them organized. SplendeoTranslator adds smarts to controllers, views, models & mailers to follow a simple convention when finding keys. Having a convention for the hierarchy of keys within locale bundles that makes it easier to code and maintain, while still using the capabilities of the underlying I18n library. (Note: SplendeoTranslator does not depend on how the actual YAML/Ruby files are stored in the filesystem.)
+
+Quick example - if you follow the key convention of structuring your locale bundle like:
+  blog_posts: # controller
+    show: # action
+      title: "My Awesome Blog Post"
+      byline: "Written by {{author}}"
+
+Then when writing the <tt>BlogPostsController.show</tt> action you can just use <tt>t('title')</tt> to fetch the string (equivalent to <tt>I18n.translate('blog_posts.show.title')</tt>). Similarly, in the <tt>show.erb</tt> template you can get use <tt>t('byline', :author => "Mike")</tt>. This extends to models and mailers as well. As they say, "Look at all the things I'm not doing!"
+
+== Installation
+
+To install this plugin into your Rails app (2.2 or 2.3+):
+
+  ./script/plugin install git://github.com/splendeo/SplendeoTranslator.git
+
+To install as a gem add the following to config/environment.rb:
+
+  config.gem "SplendeoTranslator"
+
+== RDocs
+
+{The RDocs are online}[http://splendeo.github.com/SplendeoTranslator/rdoc/index.html] or can be generated via <tt>rake rdoc</tt> in the SplendeoTranslator plugin directory.
+
+== Problems or Suggestions
+
+Please {file an issue in the Github bug tracker}[http://github.com/splendeo/SplendeoTranslator/issues/] or contact me.
+
+== Simple +translate+ Everywhere
+
+SplendeoTranslator adds an enhanced +translate+ (or shorter +t+) method to:
+* ActionController
+* ActionView
+* ActiveRecord
+* ActionMailer
+
+In the spirit of Rails, the convention for a hierarchy of keys borrows the same layout as the typical "views" directory. A sample Blog application is used as an example.
+
+For controllers/views/mailers it is:
+  en: # locale
+    # the controller name
+    blog_posts:
+      # the action name
+      index:
+        key: "Hello World"
+      
+      # partials w/o underscore (template "_footer.erb")      
+      footer: 
+        key: "My Copyright"
+    
+    # "layouts" is fixed
+    layouts:
+      # the layout name (template "main.erb")
+      main:
+        key: "My App Name"
+    
+    # for shared partials called like: render :template => "shared/user"
+    # where "shared" is the directory name
+    shared:
+      # partial name w/o underscore (template "_user.erb")
+      user:
+        key: "Foo"
+
+    # the full mailer name
+    blog_comment_mailer:
+      # the method name (does not include "deliver")
+      comment_notification:
+        subject: "New Comment"
+        
+For models it is:
+  en:
+    # The model name
+    blog_post:
+      key: "Custom validation error" 
+
+
+=== Key Lookup
+
+When a key is looked up, SplendeoTranslator adds extra scoping to the lookup based on where it is called from. For:
+* Controllers & views the scope includes <tt>[:controller_name, :action_name]</tt>. (For shared partials it is <tt>[:template_path, :partial_name]</tt>)
+* Mailers the scope includes <tt>[:mailer_name, :method_name]</tt>
+* Models the scope includes <tt>[:model_name]</tt>
+
+But what happens if you want to share strings across a controller? Let's say you have error messages that are set in flash notices
+and then are shared between actions in a controller defined in the locale bundle like:
+  blog_posts:
+    errors:
+      permission_denied: "Permission denied to read this blog post"
+
+If SplendeoTranslator doesn't find the original key, it will remove a layer of scoping and try again.
+So if in our Blogs controller +show+ action we want to set a <tt>flash[:error]</tt> to a permission denied message it can find the string by calling <tt>t('errors.permission_denied')</tt>.
+SplendeoTranslator will first look for "blog_posts.show.errors.permission_denied", which doesn't exist. So it will then try to find 
+"blog_posts.errors.permission_denied" and return the correct string. This can be used to create greater levels of scoping, or to force finding 
+global strings (e.g. <tt>t("global.app_name")</tt>).
+
+== Graceful Locale Fallback
+
+Let's say you've extracted all your English strings, and even had them translated to Spanish to make your Spanish-speaking users extra happy. Then you have a brilliant idea for a new feature that needs to go live before the new pages are translated into Spanish. You still want your Spanish-speaking users to keep seeing the site in Spanish, but for these new pages to fallback to English. (While not exactly ideal, it is better than having "translation missing" messages or not externalizing strings.) To enable this fallback behavior:
+
+  # In the configuration
+  I18n.default_locale = :en
+  
+  # Enable the fallback mode to try :es first, then :en
+  SplendeoTranslator.fallback(true)
+  
+  # Set in the code based on user's preference, their IP address, etc.
+  I18n.locale = :es
+  
+  # Everything else stays the same, but after SplendeoTranslator tries the normal scoping rules 
+  # in Spanish (:es), it will apply the same rules for the default locale (:en)
+  t('page_title')
+  
+  
+== Key fallback
+
+Let's say that you don't want to have to extract your English strings. You can use them directly as strings for other languages:
+
+  # In the configuration
+  SplendeoTranslator.key_fallback(true)
+
+  # In your views/controllers
+  t('My Title in Plain English') will return 'My Title in Plain English' if no translation is found
+
+  # In your es.yml file, you will have to quote your plain-english keys:
+  'My Title in Plain English': "Mi Título en Español"
+
+== Testing Help
+
+* <tt>SplendeoTranslator.strict_mode</tt> will cause an exception to be raised for any missing translations. Enabled by default during testing to help find mistyped or accidently forgotten keys. It can be disabled by calling <tt>SplendeoTranslator.strict_mode(false)</tt> (in test_helper for example).
+* <tt>assert_translated</tt> takes a block and asserts that all lookups within that block have real translations. It is a more targeted version of <tt>strict_mode</tt>. Example:
+
+    assert_translated do
+      # Will assert that all keys find valid translations inside the block
+      get :show
+    end
+
+* If you're trying to avoid hard-coding strings in tests, you can still use the lookup that is added to models and controllers:
+  
+    # Inside a test exercising a BlogPostController (@controller created in setup method) 
+    get :show, :id => 123
+    # the byline should be in the body - uses @controller to make lookup easy (automatically knows controller name and action)
+    assert_match @controller.t('byline', :name => "Mike"), @response.body
+
+* Pseudo-translation mode. Pseudo-translation wraps all extracted strings with leading and trailing text so that you can spot if you forgot any. It can be enabled by <tt>SplendeoTranslator.pseudo_translate</tt> (in an environment file or locale.rb for example). It does not change the lookup process (e.g. <tt>t('blog_title')</tt>) but will transform the returned string from "My Blog" to "[[ My Blog ]]". The text that is prepended / appended can be set by calling <tt>SplendeoTranslator.pseudo_prepend = "@@"</tt> (or +append+). <b>Pro Tip:</b> This can also be used to see how a layout will display in a localized language that is longer than the default. or example, German words tend to be significantly longer than their English equivalents. By padding all strings you can test how a layout will adapt and make changes.
+
+* Rake task to validate that YAML files are, in fact, valid YAML. Useful when getting back translations from a 3rd party service, this can be a quick way to catch a missing quote. Run like <tt>rake i18n:validate_yml</tt> and it will check all .yml files below <tt>RAILS_ROOT/config/locales</tt>.
+
+== Changelog
+
+1.0.0 - 4/17/2009 - Declaring 1.0 after successfully using SplendeoTranslator in production.
+
+Bug reports welcome. {Patches very welcome}[http://github.com/splendeo/SplendeoTranslator].
+
+Copyright (c) 2009 {Mike Champion}[http://splendeo.org], released under the MIT license.

data/Rakefile

@@ -0,0 +1,75 @@
+require 'rake'
+require 'rake/testtask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "translator"
+    gemspec.summary = "Rails extentions to simplify internationalization"
+    gemspec.email = "mike@graysky.org"
+    gemspec.homepage = "http://github.com/graysky/translator"
+    gemspec.description = "Translator makes using Rails internationalization simpler"
+    gemspec.authors = ["Mike Champion"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+  
+# Use Hanna for pretty RDocs (if installed), otherwise normal rdocs
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the translator plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the translator plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Translator - i18n tooling for Rails'
+  rdoc.options << '--line-numbers' << '--inline-source' << '--webcvs=http://github.com/graysky/translator/tree/master/'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Publish rdocs to Github on special gh-pages branch. Assumes local branch gh-pages"
+task :publish_rdoc do
+  # Build the rdocs
+  safe_system("rake rerdoc")
+  move("rdoc", "rdoc-tmp")
+  
+  git("co gh-pages")
+  # Remove existing docs
+  git("rm -rf --quiet rdoc")
+  move("rdoc-tmp", "rdoc")
+  # Add new ones
+  git("add .")
+  # Push the changes
+  git("commit -a -m 'updating rdocs'")
+  git("push origin HEAD")
+  
+  git("co master")
+  #system("open coverage/index.html") if PLATFORM['darwin']
+end
+
+def git(cmd)
+  safe_system("git " + cmd)
+end
+
+def safe_system(cmd)
+  if !system(cmd)
+    puts "Failed: #{cmd}"
+    exit
+  end
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 0
+:patch: 0
+:major: 1

data/lib/splendeo_translator.rb

@@ -0,0 +1,385 @@
+require 'active_support'
+require 'action_view/helpers/translation_helper'
+
+# Extentions to make internationalization (i18n) of a Rails application simpler. 
+# Support the method +translate+ (or shorter +t+) in models/view/controllers/mailers.
+module SplendeoTranslator
+  # Error for use within SplendeoTranslator
+  class SplendeoTranslatorError < StandardError #:nodoc:
+  end
+  
+  # SplendeoTranslator version
+  VERSION = '1.0.0'
+  
+  # Whether strict mode is enabled
+  @@strict_mode = false
+  
+  # Whether to fallback from the set locale to the default locale
+  @@fallback_mode = false
+  
+  # Whether to show the raw key if the locale doesn't provide a translation
+  @@key_fallback_mode = false
+  
+  # Whether to pseudo-translate all fetched strings
+  @@pseudo_translate = false
+  
+  # Pseudo-translation text to prend to fetched strings.
+  # Used as a visible marker. Default is "["
+  @@pseudo_prepend = "["
+  
+  # Pseudo-translation text to append to fetched strings.
+  # Used as a visible marker. Default is "]"
+  @@pseudo_append = "]"
+  
+  # An optional callback to be notified when there are missing translations in views
+  @@missing_translation_callback = nil
+  
+  # Invokes the missing translation callback, if it is defined
+  def self.missing_translation_callback(exception, key, options = {}) #:nodoc:
+    @@missing_translation_callback.call(exception, key, options) if !@@missing_translation_callback.nil?
+  end
+   
+  # Set an optional block that gets called when there's a missing translation within a view.
+  # This can be used to log missing translations in production.
+  #
+  # Block takes two required parameters:
+  # - exception (original I18n::MissingTranslationData that was raised for the failed translation)
+  # - key (key that was missing)
+  # - options (hash of options sent to SplendeoTranslator)
+  # Example:
+  #   set_missing_translation_callback do |ex, key, options|
+  #     logger.info("Failed to find #{key}")
+  #   end
+  def self.set_missing_translation_callback(&block)
+    @@missing_translation_callback = block
+  end
+  
+  # Performs lookup with a given scope. The scope should be an array of strings or symbols
+  # ordered from highest to lowest scoping. For example, for a given PicturesController 
+  # with an action "show" the scope should be ['pictures', 'show'] which happens automatically.
+  #
+  # The key and options parameters follow the same rules as the I18n library (they are passed through).
+  # 
+  # The search order is from most specific scope to most general (and then using a default value, if provided).
+  # So continuing the previous example, if the key was "title" and options included :default => 'Some Picture'
+  # then it would continue searching until it found a value for:
+  # * pictures.show.title
+  # * pictures.title
+  # * title
+  # * use the default value (if provided)
+  #
+  # The key itself can contain a scope. For example, if there were a set of shared error messages within the 
+  # Pictures controller, that could be found using a key like "errors.deleted_picture". The inital search with
+  # narrowest scope ('pictures.show.errors.deleted_picture') will not find a value, but the subsequent search with
+  # broader scope ('pictures.errors.deleted_picture') will find the string.
+  #
+  def self.translate_with_scope(scope, key, options={})
+    scope ||= [] # guard against nil scope
+    
+    # Let Rails 2.3 handle keys starting with "."
+    raise SplendeoTranslatorError, "Skip keys with leading dot" if key.to_s.first == "."
+    
+    # Keep the original options clean
+    original_scope = scope.dup
+    scoped_options = {}.merge(options)
+        
+    # Raise to know if the key was found
+    scoped_options[:raise] = true
+    
+    # Remove any default value when searching with scope
+    scoped_options.delete(:default)
+    
+    str = nil # the string being looked for
+    
+    # Loop through each scope until a string is found.
+    # Example: starts with scope of [:blog_posts :show] then tries scope [:blog_posts] then 
+    # without any automatically added scope ("[]").
+    while str.nil?
+      # Set scope to use for search
+      scoped_options[:scope] = scope
+    
+      begin
+        # try to find key within scope (dup the options because I18n modifies the hash)
+        str = I18n.translate(key, scoped_options.dup)
+      rescue I18n::MissingTranslationData => exc
+        # did not find the string, remove a layer of scoping.
+        # break when there are no more layers to remove (pop returns nil)
+        break if scope.pop.nil?
+      end
+    end
+
+    # return the key itself if translator is on key_fallback mode
+    str ||= key if SplendeoTranslator.key_fallback?
+    
+    # If a string is not yet found, potentially check the default locale if in fallback mode.
+    if str.nil? && SplendeoTranslator.fallback? && (I18n.locale != I18n.default_locale) && options[:locale].nil?
+      # Recurse original request, but in the context of the default locale
+      str ||= SplendeoTranslator.translate_with_scope(original_scope, key, options.merge({:locale => I18n.default_locale}))
+    end
+    
+    # If a string was still not found, fall back to trying original request (gets default behavior)
+    str ||= I18n.translate(key, options)
+    
+    # If pseudo-translating, prepend / append marker text
+    if SplendeoTranslator.pseudo_translate? && !str.nil?
+      str = SplendeoTranslator.pseudo_prepend + str + SplendeoTranslator.pseudo_append
+    end
+    
+    str
+  end
+  
+  class << SplendeoTranslator
+    
+    # Generic translate method that mimics <tt>I18n.translate</tt> (e.g. no automatic scoping) but includes locale fallback
+    # and strict mode behavior.
+    def translate(key, options={})
+      SplendeoTranslator.translate_with_scope([], key, options)
+    end
+    
+    alias :t :translate
+  end
+  
+  # When fallback mode is enabled if a key cannot be found in the set locale,
+  # it uses the default locale. So, for example, if an app is mostly localized
+  # to Spanish (:es), but a new page is added then Spanish users will continue
+  # to see mostly Spanish content but the English version (assuming the <tt>default_locale</tt> is :en)
+  # for the new page that has not yet been translated to Spanish.
+  def self.fallback(enable = true)
+    @@fallback_mode = enable
+  end
+  
+  # If fallback mode is enabled
+  def self.fallback?
+    @@fallback_mode
+  end
+  
+  # When key_fallback mode is enabled, if a key cannot be found in the set locale,
+  # it will return the key
+  def self.key_fallback(enable = true)
+    @@key_fallback_mode = enable
+  end
+  
+  # If key_fallback mode is enabled
+  def self.key_fallback?
+    @@key_fallback_mode
+  end
+  
+  # Toggle whether to true an exception on *all* +MissingTranslationData+ exceptions
+  # Useful during testing to ensure all keys are found.
+  # Passing +true+ enables strict mode, +false+ installs the default exception handler which
+  # does not raise on +MissingTranslationData+
+  def self.strict_mode(enable_strict = true)
+    @@strict_mode = enable_strict
+    
+    if enable_strict
+      # Switch to using contributed exception handler
+      I18n.exception_handler = :strict_i18n_exception_handler
+    else
+      I18n.exception_handler = :default_exception_handler
+    end
+  end
+  
+  # Get if it is in strict mode
+  def self.strict_mode?
+    @@strict_mode
+  end
+  
+  # Toggle a pseudo-translation mode that will prepend / append special text
+  # to all fetched strings. This is useful during testing to view pages and visually
+  # confirm that strings have been fully extracted into locale bundles.
+  def self.pseudo_translate(enable = true)
+    @@pseudo_translate = enable
+  end
+  
+  # If pseudo-translated is enabled
+  def self.pseudo_translate?
+    @@pseudo_translate
+  end
+  
+  # Pseudo-translation text to prepend to fetched strings.
+  # Used as a visible marker. Default is "[["
+  def self.pseudo_prepend
+    @@pseudo_prepend
+  end
+  
+  # Set the pseudo-translation text to prepend to fetched strings.
+  # Used as a visible marker.
+  def self.pseudo_prepend=(v)
+    @@pseudo_prepend = v
+  end
+
+  # Pseudo-translation text to append to fetched strings.
+  # Used as a visible marker. Default is "]]"
+  def self.pseudo_append
+    @@pseudo_append
+  end
+  
+  # Set the pseudo-translation text to append to fetched strings.
+  # Used as a visible marker.
+  def self.pseudo_append=(v)
+    @@pseudo_append = v
+  end
+  
+  # Additions to TestUnit to make testing i18n easier
+  module Assertions
+    
+    # Assert that within the block there are no missing translation keys.
+    # This can be used in a more tailored way that the global +strict_mode+
+    #
+    # Example:
+    #   assert_translated do
+    #     str = "Test will fail for #{I18n.t('a_missing_key')}"
+    #   end
+    #
+    def assert_translated(msg = nil, &block)
+      
+      # Enable strict mode to force raising of MissingTranslationData
+      SplendeoTranslator.strict_mode(true)
+      
+      msg ||= "Expected no missing translation keys"
+      
+      begin
+        yield
+        # Credtit for running the assertion
+        assert(true, msg)
+      rescue I18n::MissingTranslationData => e
+        # Fail!
+        assert_block(build_message(msg, "Exception raised:\n?", e)) {false}
+      ensure
+        # uninstall strict exception handler
+        SplendeoTranslator.strict_mode(false)
+      end
+        
+    end
+  end
+  
+  module I18nExtensions
+    # Add an strict exception handler for testing that will raise all exceptions
+    def strict_i18n_exception_handler(exception, locale, key, options)
+      # Raise *all* exceptions
+      raise exception
+    end
+    
+  end
+end
+
+module ActionView #:nodoc:
+  class Base
+    # Redefine the +translate+ method in ActionView (contributed by TranslationHelper) that is
+    # context-aware of what view (or partial) is being rendered. 
+    # Initial scoping will be scoped to [:controller_name :view_name]
+    def translate_with_context(key, options={})
+      # default to an empty scope
+      scope = []
+
+      # Use the template for scoping if there is a templ
+      unless self.template.nil?
+        # The outer scope will typically be the controller name ("blog_posts")
+        # but can also be a dir of shared partials ("shared").
+        outer_scope = self.template.base_path
+        
+        # The template will be the view being rendered ("show.erb" or "_ad.erb")
+        inner_scope = self.template.name
+        
+        # Partials template names start with underscore, which should be removed
+        inner_scope.sub!(/^_/, '')
+
+        scope = [outer_scope, inner_scope]
+      end
+      
+      # In the case of a missing translation, fall back to letting TranslationHelper
+      # put in span tag for a translation_missing.
+      begin
+        SplendeoTranslator.translate_with_scope(scope, key, options.merge({:raise => true}))
+      rescue SplendeoTranslator::SplendeoTranslatorError, I18n::MissingTranslationData => exc
+        # Call the original translate method
+        str = translate_without_context(key, options)
+        
+        # View helper adds the translation missing span like:
+        # In strict mode, do not allow TranslationHelper to add "translation missing" span like:
+        # <span class="translation_missing">en, missing_string</span>
+        if str =~ /span class\=\"translation_missing\"/
+          # In strict mode, do not allow TranslationHelper to add "translation missing"
+          raise if SplendeoTranslator.strict_mode?
+          
+          # Invoke callback if it is defined
+          SplendeoTranslator.missing_translation_callback(exc, key, options)
+        end
+
+        str
+      end
+    end
+  
+    alias_method_chain :translate, :context
+    alias :t :translate
+  end
+end
+
+module ActionController #:nodoc:
+  class Base
+    
+    # Add a +translate+ (or +t+) method to ActionController that is context-aware of what controller and action
+    # is being invoked. Initial scoping will be [:controller_name :action_name] when looking up keys. Example would be
+    # +['posts' 'show']+ for the +PostsController+ and +show+ action.
+    def translate_with_context(key, options={})
+      SplendeoTranslator.translate_with_scope([self.controller_name, self.action_name], key, options)
+    end
+  
+    alias_method_chain :translate, :context
+    alias :t :translate
+  end
+end
+
+module ActiveRecord #:nodoc:
+  class Base
+    # Add a +translate+ (or +t+) method to ActiveRecord that is context-aware of what model is being invoked. 
+    # Initial scoping of [:model_name] where model name is like 'blog_post' (singular - *not* the table name) 
+    def translate(key, options={})
+      SplendeoTranslator.translate_with_scope([self.class.name.underscore], key, options)
+    end
+  
+    alias :t :translate  
+  
+    # Add translate as a class method as well so that it can be used in validate statements, etc.
+    class << Base
+    
+      def translate(key, options={}) #:nodoc:
+        SplendeoTranslator.translate_with_scope([self.name.underscore], key, options)
+      end
+    
+      alias :t :translate
+    end
+  end
+end
+
+module ActionMailer #:nodoc:
+  class Base
+
+    # Add a +translate+ (or +t+) method to ActionMailer that is context-aware of what mailer and action
+    # is being invoked. Initial scoping of [:mailer_name :action_name] where mailer_name is like 'comment_mailer' 
+    # and action_name is 'comment_notification' (note: no "deliver_" or "create_")
+    def translate(key, options={})
+      SplendeoTranslator.translate_with_scope([self.mailer_name, self.action_name], key, options)
+    end
+
+    alias :t :translate
+  end
+end
+
+module I18n
+  # Install the strict exception handler for testing
+  extend SplendeoTranslator::I18nExtensions
+end
+
+module Test # :nodoc: all
+  module Unit
+    class TestCase
+      include SplendeoTranslator::Assertions
+    end
+  end
+end
+
+# In test environment, enable strict exception handling for missing translations
+if (defined? RAILS_ENV) && (RAILS_ENV == "test")
+  SplendeoTranslator.strict_mode(true)
+end