r18n-core 0.3.2 → 0.4

data/ChangeLog

@@ -1,3 +1,14 @@
+== 0.4 (D-Day)
+* Rails I18n compatibility.
+* Rewrite a lot of core code to fast and cleanup version.
+* Custom translation loaders.
+* Add reload! method to I18n.
+* Add t and l helpers to Sinatra and desktop plugins.
+* Syntax sugar for default values.
+* Named variables.
+* New locale API.
+* Change API for extension translations.
+
 == 0.3.2 (Pidgin)
 * Print path of untranslated string by filters.
 * Add Italian locale (by Guido De Rosa).

data/README.rdoc

@@ -1,26 +1,150 @@
 = R18n
 
-R18n is a i18n tool to translate your Ruby application in several languages.
+R18n is a i18n tool to translate your Ruby application to several languages.
 
-Use <tt>sinatra-r18n</tt> or teamon’s <tt>merb_i18n</tt> to localize Web applications and 
-<tt>r18n-desktop</tt> to localize desktop application.
+Use <tt>r18n-rails</tt>, <tt>sinatra-r18n</tt> or teamon’s <tt>merb_i18n</tt> to
+localize Web applications and <tt>r18n-desktop</tt> to localize desktop
+application.
 
 == Features
 
-* It has special support for countries with two official languages. If there
-  isn’t translation in user locale, it will be found in locales, which
-  user may know (not only in default locale). For example, many people in 
-  Belarus can understand Russian, and locale has information about it.
-* It can format numbers and time to the rules of the user locale, translate
-  month and week days name and give other locale information.
-* It has translation for commons words, like “OK”, “Cancel”, etc.
-* It storage translation in rich YAML format. You can put procedures and
-  pluralization (“1 comment”, “5 comments”) or create you own filters.
-* It can translate Web and desktop applications.
+=== Ruby-style Syntax
+R18n uses hierarchical not English-centrist YAML format for translations by
+default:
+
+  user:
+    edit: Edit user
+    name: User name is %1
+    count: !!pl
+      1: There is 1 user
+      n: There are %1 users
+
+To access translation you can call methods with same names:
+
+  t.user.edit         #=> "Edit user"
+  t.user.name('John') #=> "User name is John"
+  t.user.count(5)     #=> "There are 5 users"
+  
+  t.not.exists | 'default' #=> "default"
+  t.not.exists.translated? #=> false
+
+If translation key has name of Object method you can use another way:
+
+  t[:methods] #=> "Methods"
+
+=== Filters
+
+You can add custom filters for some YAML type or any translated strings.
+Filters are cascade and can communicate with each other.
+
+R18n already has filters for HTML escaping, lambdas, Textile and Markdown:
+
+  hi: !!markdown
+    **Hi**, people!
+  greater: !!escape
+    1 < 2 is true
+
+  t.hi      #=> "<p><strong>Hi</strong>, people!</p>"
+  t.greater #=> "1 &lt; 2 is true"
+
+=== Flexibility
+
+Translation variables and pluralization (“1 comment”, “5 comments”) are filters
+too. So you can extend or replace it. For example, you can use named variables
+filter from <tt>r18n-rails-api</tt> gem:
+
+  greeting: "Hi, {{name}}"
+
+  R18n::Filters.on(:named_variables)
+  t.greeting(name: 'John') #=> "Hi, John"
+
+=== Flexible Locales
+
+Locale can extend Locale class, so locales are very flexible. For example,
+English locale extend time formatters:
+
+  l Date.now, :full #=> "30th of November, 2009"
+
+Or Russian has built-in different pluralization without any lambdas in YAML:
+
+  t.user.count(1) #=> "1 пользователь"
+  t.user.count(2) #=> "2 пользователя"
+  t.user.count(5) #=> "5 пользователей"
+
+=== Loaders
+
+R18n can load translations from any places, not just from YAML files. You just
+need to create loader object with 2 methods: +available+ and +load+:
+
+  class DBLoader
+    def available
+      Translation.find(:all).map(&:locale)
+    end
+    def load(locale)
+      Translation.find(locale).to_hash
+    end
+  end
+  
+  R18n.set R18n::I18n.new(user_locales, DBLoader.new)
+
+You can also set a list of different translation places or set extension places,
+which will be used only with application translation (useful for plugins).
+
+=== Object Translation
+
+You can translate any class, including ORM models:
+
+  require 'r18n-core/translated'
+  
+  class Product < ActiveRecord::Base
+    include R18n::Translated
+    # Model has two usual property: title_en and title_ru
+    translations :title
+  end
+  
+  # For English user
+  product.title #=> "Anthrax"
+  
+  # For Russian user
+  product.title #=> "Сибирская язва"
+
+=== Localization
+
+R18n can localize numbers and time:
+
+  l -5000                 #=> "−5,000"
+  l Time.now              #=> "30/11/2009 14:36"
+  l Time.now, :full       #=> "30th of November, 2009 14:37"
+  l Time.now - 60, :human #=> "1 minute ago"
+
+=== Several User Languages
+
+Lack of translation in user language isn’t exception for R18n (because
+translation to not primary language done by enthusiasts, it can be out of date).
+R18n just automatically take next user language (browser send a list of locales)
+and for cultures with two officially languages (e.g., exUSSR) it take second
+language (e.g., if translation isn’t available in Kazakh R18n will see in
+Russian):
+
+  i18n = R18n::I18n.new(['kk', 'de'], 'dir/with/translations')
+  
+  i18n.locales    #=> [Locale kk (Қазақша), Locale de (Deutsch),
+                  #    Locale ru (Русский), Locale en (English)]
+  
+  i18n.kazakh  #=> "Қазақша", main user language
+  i18n.deutsch #=> "Deutsch", not in Kazakh, use next user locale
+  i18n.russian #=> "Русский", not in kk and de, use Kazakh sublocale
+  i18n.english #=> "English", not in any user locales, use default
+
+=== Agnostic
+
+R18n has a agnostic core package and plugins with out-of-box support for
+Sinatra, Merb and desktop applications.
 
 == Usage
 
 === Translation
+
 Translation files use YAML format and has name like en.yml (English) or
 en-us.yml (USA English dialect) with language/country code (RFC 3066).
 
@@ -43,18 +167,18 @@ In translation you can use:
 To get translated string use method with key name or square brackets [] for
 keys, which is same with Object methods (+class+, +inspect+, etc):
 
-  i18n.robot    #=> "This is robot"
-  i18n["robot"] #=> "This is robot"
+  t.robot    #=> "This is robot"
+  t[:robot]  #=> "This is robot"
 
 Translation may be hierarchical:
 
-  i18n.post.add       #=> "Add post"
-  i18n['post']['add'] #=> "Add post"
+  t.post.add     #=> "Add post"
+  t[:post][:add] #=> "Add post"
 
 If locale willn’t be found in user locale R18n will search it in they sublocales
 or in another locale, which user know:
 
-  i18n.no.in.english #=> "В английском нет"
+  t.no.in.english #=> "В английском нет"
 
 Translated string has +locale+ method and you can get it locale (Locale instance
 or code string if locale is’t supported in R18n):
@@ -65,26 +189,36 @@ You can replace some parameters in translated string by put it as arguments:
   
   name: "My name is %1"
 
-  i18n.name('John') #=> "My name is John"
+  t.name('John') #=> "My name is John"
 
 Pluralizable messages get item count from first argument:
 
-  i18n.robots(0)  #=> "No robots"
-  i18n.robots(1)  #=> "One robot"
-  i18n.robots(50) #=> "50 robots"
+  t.robots(0)  #=> "No robots"
+  t.robots(1)  #=> "One robot"
+  t.robots(50) #=> "50 robots"
 
-If there isn’t pluralization for some number, translation will be use 'n'. If
+If there isn’t pluralization for some number, translation will be use +n+. If
 there isn’t locale file for translation, it will be use English pluralization
-rule (0, 1 and 'n').
+rule (0, 1 and +n+).
+
+You can check, is message has translation:
+
+  t.post.add.translated?   #=> true
+  t.not.exists.translated? #=> false
+
+For untranslated strings you can set default value:
+
+  t.not.exists | 'default' #=> "default"
 
 R18n already has translation for common words for most supported locales.
 See <tt>base/</tt> in dir in gem.
 
-  i18n.yes    #=> "Yes"
-  i18n.cancel #=> "Cancel"
-  i18n.delete #=> "Delete"
+  t.yes    #=> "Yes"
+  t.cancel #=> "Cancel"
+  t.delete #=> "Delete"
 
 === Filters
+
 You can also add you own filter for translations: escape HTML entries, convert
 from Markdown syntax, etc.
 
@@ -95,7 +229,7 @@ from Markdown syntax, etc.
     content + '!'
   end
   
-  i18n.filtered('_') #=> "This_content_will_be_processed_by_filter!"
+  t.filtered('_') #=> "This_content_will_be_processed_by_filter!"
 
 You can also add global filters for all translated strings:
 
@@ -104,13 +238,14 @@ You can also add global filters for all translated strings:
   end
 
 ==== HTML Escape
+
 R18n contain 2 filters to escape HTML entries: by YAML type and global. If you
 need to escape HTML in some translations, just set <tt>!!escape</tt> YAML type:
 
   greater: !!escape
     1 < 2 is true
 
-  i18n.greater #=> "1 &lt; 2 is true"
+  t.greater #=> "1 &lt; 2 is true"
 
 If you develop web application and want to escape HTML in all translations, just
 activate global escape filter:
@@ -124,31 +259,34 @@ disable escaping in some special value.
     <b>Warning</b>
 
   R18n::Filters.on(:global_escape_html)
-  i18n.warning #=> "<b>Warning</b>"
+  t.warning #=> "<b>Warning</b>"
 
 ==== Markdown
+
 To use Markdown in your translations you must install maruku gem:
 
   hi: !!markdown
     **Hi**, people!
 
-  i18n.hi #=> "<p><strong>Hi</strong>, people!</p>"
+  t.hi #=> "<p><strong>Hi</strong>, people!</p>"
 
 
 ==== Textile
+
 To use Textile in your translations you must install RedCloth gem:
 
   alarm: !!textile
     It will delete _all_ users!
 
-  i18n.alarm #=> "<p>It will delete <em>all</em> users!</p>"
+  t.alarm #=> "<p>It will delete <em>all</em> users!</p>"
 
 ==== Lambdas
+
 You can use lambdas in your translations.
 
   sum: !!proc |x, y| x + y
 
-  i18n.sum(1, 2) #=> 3
+  t.sum(1, 2) #=> 3
 
 If it isn’t secure in your application (for example, user can change
 translations), you can disable it:
@@ -156,9 +294,10 @@ translations), you can disable it:
   R18n::Filters.off(:procedure)
 
 === Localization
+
 You can print number and float according to the rules of the user locale:
 
-  i18n.l -12000.5 #=> "−12,000.5"
+  l -12000.5 #=> "−12,000.5"
 
 Number and float formatters will also put real typographic minus and put
 non-break thin spaces (for locale, which use it as digit separator).
@@ -166,17 +305,18 @@ non-break thin spaces (for locale, which use it as digit separator).
 You can translate months and week days names in Time, Date and DateTime by
 +strftime+ method:
 
-  i18n.l Time.now, '%B'  #=> "September"
+  l Time.now, '%B'  #=> "September"
 
 R18n has some time formats for locales: <tt>:human</tt>, <tt>:full</tt> and
 <tt>:standard</tt> (by default):
 
-  i18n.l Time.now, :human #=> "now"
-  i18n.l Time.now, :full  #=> "August 9th, 2009 21:47"
-  i18n.l Time.now         #=> "08/09/2009 21:41"
-  i18n.l Time.now.to_date #=> "08/09/2009"
+  l Time.now, :human #=> "now"
+  l Time.now, :full  #=> "August 9th, 2009 21:47"
+  l Time.now         #=> "08/09/2009 21:41"
+  l Time.now.to_date #=> "08/09/2009"
 
 === Model
+
 You can add i18n support to any classes, including ORM models:
 
   require 'r18n-core/translated'
@@ -206,6 +346,7 @@ You can add i18n support to any classes, including ORM models:
 See R18n::Translated for documentation.
 
 === Locale
+
 All supported locales are storage in R18n gem at +locales+ dir. If you want to
 add your locale, please write me to andrey@sitnik.ru.
 
@@ -223,37 +364,68 @@ You can get from locale:
   
     locale.ltr? #=> true
   
-* Week start day ("sunday" or "monday"):
+* Week start day (+:monday+ or +:sunday+):
+  
+    locale.week_start #=> :sunday
+
+=== Loaders
+
+You can load translations from any ways, not just from YAML files. To load
+translation you must create loader class with 2 methods:
+* <tt>available</tt> – return array of locales of available translations;
+* <tt>load(locale)</tt> – return Hash of translation.
+And put it instance to <tt>R18n::I18n.new</tt>:
+
+  R18n.set R18n::I18n.new('en', MyLoader.new(loader_param))
+
+You can set your loader as default and pass to <tt>R18n::I18n.new</tt> only
+constructor argument:
+
+  R18n.default_loader = MyLoader
+  R18n.set R18n::I18n.new('en', loader_param)
+
+If you want to load translation with some type for filter, use
+<tt>R18n::Typed</tt> struct:
+
+  # Loader load method return something like:
+  { 'users' => R18n::Typed.new('pl', { 1 => '1 user', 'n' => '%1 users' }) }
   
-    locale['week']['start'] #=> "sunday"
+  # To use pluralization filter (+pl+ type):
+  t.users(5) #=> "5 users"
+
+=== Extension Translations
+
+For r18n plugin you can add loaders with translations, which will be used with
+application translations. For example, DB plugin may place translations for
+error messages in extension dir. R18n contain translations for base words as
+extension dir too.
+
+  R18n.extension_places << R18n::Loader::YAML.new('./error_messages/')
+
+== Add Locale
 
-== Add locale
 If R18n hasn’t locale file for your language, please add it. It’s very simple:
-* Create in locales/ file _code_.yml for your language and describe locale.
+* Create in locales/ file _code_.rb for your language and describe locale.
   Just copy from another locale and change different values.
-  * If your language is dialect or base on another (as American English (en-US) 
-    base on English (en)) write <tt>include: _base_locale_</tt> and similar
-    values can be deleted.
   * If in your country people mostly know another language (like in exUSSR
-    countries people know Russian), write
-    <tt>sublocales: [_another_locale_, en]</tt>. Else write only:
-    <tt>sublocales: [en]</tt>. For dialect put base locale to +sublocales+ too.
+    countries people know Russian), add
+    <tt>sublocales %{_another_locale_ en}</tt>.
 * Create in base/ file _code_.yml for your language and translate base messages.
   Just copy file from language, which you know, and rewrite values.
 * If you language need some special logic (for example, different pluralization
-  or time formatters) you can change Locale class. Create in locales/ file
-  _code_.rb and write R18n::Locales::_Code_ class, which must extend
-  R18n::Locale.
+  or time formatters) you can extend Locale class methods.
 * Push files by GitHub (http://github.com/ai/r18n) or just write e-mail with
   this files to me (andrey@sitnik.ru).
 
 _Code_ is RFC 3066 code for your language (for example, “en” for English and
-“fr_CA” for Canadian French). You can send to my e-mail any questions (on
+“fr-CA” for Canadian French). You can send to my e-mail any questions (on
 http://sitnik.ru you find another contact addresses).
 
 == License
+
 R18n is licensed under the GNU Lesser General Public License version 3.
 You can read it in LICENSE file or in http://www.gnu.org/licenses/lgpl.html.
 
 == Author
+
 Andrey “A.I.” Sitnik <andrey@sitnik.ru>

data/lib/r18n-core/filters.rb

@@ -51,17 +51,17 @@ module R18n
   # OpenStruct and you can add you own parameter to cross-filter communications:
   # 
   #   R18n::Filters.add(String, :hide_truth) do |content, config|
-  #     return content if config.censorship_check
+  #     return content if config[:censorship_check]
   #     
-  #     if content.scan(CENSORSHIP_WORDS[config.locale]).empty?
+  #     if content.scan(CENSORSHIP_WORDS[config[:locale]]).empty?
   #       content
   #     else
-  #       "Error in #{config.path}"
+  #       "Error in #{config[:path]}"
   #     end
   #   end
   #   
   #   R18n::Filters.add('passed', :show_lie) do |content, config|
-  #     config.censorship_check = true
+  #     config[:censorship_check] = true
   #     content
   #   end
   # 
@@ -99,30 +99,31 @@ module R18n
         @by_type ||= Hash.new([])
       end
       
-      # Process +translation+ by global filters and filters for special +type+.
-      def process(translation, locale, path, type, params)
-        case translation
-        when Numeric, NilClass, FalseClass, TrueClass, Symbol
-        else
-          translation = translation.clone
-        end
-        config = OpenStruct.new(:locale => locale, :path => path)
+      # Process +value+ by global filters and filters for special +type+.
+      def process(type, value, locale, path, params)
+        config = { :locale => locale, :path => path }
         
-        if type
-          filters = Filters.enabled[type]
-          filters.each { |f| translation = f.call(translation, config, *params)}
-        end
+        Filters.enabled[type].each { |f| value = f.call(value, config, *params)}
         
-        if translation.is_a? String
-          Filters.enabled[String].each do |f|
-            translation = f.call(translation, config, *params)
-          end
-          return TranslatedString.new(translation, locale, path)
+        if value.is_a? String
+          value = TranslatedString.new(value, locale, path)
+          process_string(value, config, params)
         else
-          translation
+          value
         end
       end
       
+      # Process +value+ by global filters.
+      def process_string(value, config, params)
+        if config.is_a? String
+          config = { :locale => value.locale, :path => config }
+        end
+        Filters.enabled[String].each do |f|
+          value = f.call(value, config, *params)
+        end
+        value
+      end
+      
       # Add new filter for +type+ with +name+ and return filter object. You
       # can use String class as +type+ to add global filter for all translated
       # string.
@@ -196,20 +197,19 @@ module R18n
   end
   
   Filters.add('pl', :pluralization) do |content, config, param|
-    type = config.locale.pluralize(param)
-    type = 'n' if not content.include? type
-    content[type]
+    if param.is_a? Numeric
+      type = config[:locale].pluralize(param)
+      type = 'n' if not content.has_key? type
+      content[type]
+    else
+      content
+    end
   end
   
   Filters.add(String, :variables) do |content, config, *params|
     content = content.clone
     params.each_with_index do |param, i|
-      if param.is_a? Float
-        param = config.locale.format_float(param)
-      elsif param.is_a? Integer
-        param = config.locale.format_integer(param)
-      end
-      content.gsub! "%#{i+1}", param.to_s
+      content.gsub! "%#{i+1}", config[:locale].localize(param)
     end
     content
   end
@@ -219,17 +219,17 @@ module R18n
   end
   
   Filters.add('escape', :escape_html) do |content, config|
-    config.dont_escape_html = true
+    config[:dont_escape_html] = true
     Utils.escape_html(content)
   end
   
   Filters.add('html', :dont_escape_html) do |content, config|
-    config.dont_escape_html = true
+    config[:dont_escape_html] = true
     content
   end
   
   Filters.add(String, :global_escape_html) do |content, config|
-    if config.dont_escape_html
+    if config[:dont_escape_html]
       content
     else
       Utils.escape_html(content)