r18n-core 0.2.3 → 0.3

data/README.rdoc

@@ -2,7 +2,7 @@
 
 R18n is a i18n tool to translate your Ruby application in several languages.
 
-Use <tt>merb_r18n</tt> to localize Merb Web application and 
+Use <tt>sinatra-r18n</tt> or teamon’s +merb_i18n+ to localize Web applications and 
 <tt>r18n-desktop</tt> to localize desktop application.
 
 == Features
@@ -15,36 +15,14 @@ Use <tt>merb_r18n</tt> to localize Merb Web application and
   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”) in your translation.
+  pluralization (“1 comment”, “5 comments”) or create you own filters.
 * It can translate Web and desktop applications.
 
 == Usage
 
-=== 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.
-
-To get information about locale create R18n::Locale instance:
-
-  locale = R18n::Locale.load('en')
-
-You can get from locale:
-* Locale title and RFC 3066 code:
-  
-    locale['title'] #=> "English"
-    locale['code'] #=> "en"
-  
-* Language direction (left to right, or right to left for Arabic and Hebrew):
-  
-    locale['direction'] #=> "ltr"
-  
-* Week start day ("sunday" or "monday")
-  
-    locale['week']['start'] #=> "sunday"
-
 === 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).
+en-us.yml (USA English dialect) with language/country code (RFC 3066).
 
 In translation you can use:
 * Strings
@@ -58,8 +36,9 @@ In translation you can use:
       0: No robots
       1: One robot
       n: %1 robots
-* Procedures
-    sum: !!proc |x, y| x + y
+* Filters
+    filtered: !!custom_type
+      This content will be processed by filter
 
 To get translated string use method with key name or square brackets [] for
 keys, which is same with Object methods (+class+, +inspect+, etc):
@@ -105,6 +84,77 @@ See <tt>base/</tt> in dir in gem.
   i18n.cancel #=> "Cancel"
   i18n.delete #=> "Delete"
 
+=== Filters
+You can also add you own filter for translations: escape HTML entries, convert
+from Markdown syntax, etc.
+
+  R18n::Filters.add('custom_type', :filter_name) do |content, config, replace|
+    content.gsub(' ', replace)
+  end
+  R18n::Filters.add('custom_type') do |content, config, replace|
+    content + '!'
+  end
+  
+  i18n.filtered('_') #=> "This_content_will_be_processed_by_filter!"
+
+You can also add global filters for all translated strings:
+
+  R18n::Filters.add(String, :capitalize_ruby) do |content, config|
+    content.gsub(/ruby/i) { |i| i.swapcase }
+  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"
+
+If you develop web application and want to escape HTML in all translations, just
+activate global escape filter:
+
+  R18n::Filters.on(:global_escape_html)
+
+If you enable global HTML escape, you may use <tt>!!html</tt> YAML type to
+disable escaping in some special value.
+
+  warning: !!html
+    <b>Warning</b>
+
+  R18n::Filters.on(:global_escape_html)
+  i18n.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>"
+
+
+==== 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>"
+
+==== Lambdas
+You can use lambdas in your translations.
+
+  sum: !!proc |x, y| x + y
+
+  i18n.sum(1, 2) #=> 3
+
+If it isn’t secure in your application (for example, user can change
+translations), you can disable it:
+
+  R18n::Filters.off(:procedure)
+
 === Localization
 You can print number and float according to the rules of the user locale:
 
@@ -116,18 +166,90 @@ 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"
+  i18n.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"
+
+=== Model
+You can add i18n support to any classes, including ORM models:
+
+  require 'r18n-core/translated'
+  
+  class Product
+    include DataMapper::Resource
+    property :title_ru, String
+    property :title_en, String
+    
+    include R18n::Translated
+    translations :title
+  end
+  
+  # For example, user know only Russian
+  
+  # Set value to English (default) title
+  product.title_en = "Anthrax"
+  product.title #=> "Anthrax"
+  
+  # Set value to title on user locale (Russian)
+  product.title = "Сибирская язва"
+  product.title #=> "Сибирская язва"
+  
+  product.title_en #=> "Anthrax"
+  product.title_ru #=> "Сибирская язва"
+
+See R18n::Translated for documentation.
 
-R18n has some time formats for locales: <tt>:month</tt>, <tt>:time</tt>,
-<tt>:date</tt>, <tt>:short_data</tt>, <tt>:long_data</tt>, <tt>:datetime</tt>,
-<tt>:short_datetime</tt> and <tt>:long_datetime</tt>:
+=== 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.
 
-  i18n.l Time.now, :date #=> "09/21/2008"
+To get information about locale create R18n::Locale instance:
+
+  locale = R18n::Locale.load('en')
 
-By default +strftime+ will be use <tt>:datetime</tt> format for Time and
-DateTime and <tt>:date</tt> for Date:
+You can get from locale:
+* Locale title and RFC 3066 code:
+  
+    locale.title #=> "English"
+    locale.code  #=> "en"
+  
+* Language direction (left to right, or right to left for Arabic and Hebrew):
+  
+    locale.ltr? #=> true
+  
+* Week start day ("sunday" or "monday"):
+  
+    locale['week']['start'] #=> "sunday"
 
-  i18n.l Time.now        #=> "Sun Sep 21 19:50:04 GMT 2008"
+== 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.
+  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.
+* 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.
+* 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
+http://sitnik.ru you find another contact addresses).
 
 == License
 R18n is licensed under the GNU Lesser General Public License version 3.

data/base/cs.yml

@@ -0,0 +1,34 @@
+ok: OK
+save: Uložit
+cancel: Zrušit
+yes: Ano
+no: Ne
+exit: Konec
+delete: Smazat
+
+human_time:
+  after_days: !!pl
+    1: za %1 den
+    2: za %1 dny
+    n: za %1 dnů
+  tomorrow: zítra
+  after_hours: !!pl
+    1: za %1 hodinu
+    2: za %1 hodiny
+    n: za %1 hodin
+  after_minutes: !!pl
+    1: za %1 minutu
+    2: za %1 minuty
+    n: za %1 minut
+  now: teď
+  today: dnes
+  minutes_ago: !!pl
+    1: před %1 minutou
+    n: před %1 minutami
+  hours_ago: !!pl
+    1: před %1 hodinou
+    n: před %1 hodinami
+  yesterday: včera
+  days_ago: !!pl
+    1: před %1 dnem
+    n: před %1 dny

data/base/de.yml

@@ -5,3 +5,27 @@ yes: Ja
 no: Nein
 exit: Ausgang
 delete: Löschen
+
+human_time:
+  after_days: !!pl
+    1: nach %1 Tag
+    n: nach %1 Tagen
+  tomorrow: morgen
+  after_hours: !!pl
+    1: nach %1 Stunde
+    n: nach %1 Stunden
+  after_minutes: !!pl
+    1: nach %1 Minute
+    n: nach %1 Minuten
+  now: jetzt
+  today: heute
+  minutes_ago: !!pl
+    1: %1 Minute vor
+    n: %1 Minuten vor
+  hours_ago: !!pl
+    1: %1 Stunde vor
+    n: %1 Stunden vor
+  yesterday: gestern
+  days_ago: !!pl
+    1: %1 Tag vor
+    n: %1 Tagen vor

data/base/en.yml

@@ -5,3 +5,27 @@ yes: Yes
 no: No
 exit: Exit
 delete: Delete
+
+human_time:
+  after_days: !!pl
+    1: after %1 day
+    n: after %1 days
+  tomorrow: tomorrow
+  after_hours: !!pl
+    1: after %1 hour
+    n: after %1 hours
+  after_minutes: !!pl
+    1: after %1 minute
+    n: after %1 minutes
+  now: now
+  today: today
+  minutes_ago: !!pl
+    1: %1 minute ago
+    n: %1 minutes ago
+  hours_ago: !!pl
+    1: %1 hour ago
+    n: %1 hours ago
+  yesterday: yesterday
+  days_ago: !!pl
+    1: %1 day ago
+    n: %1 days ago

data/base/fr.yml

@@ -5,3 +5,27 @@ yes: Oui
 no: Non
 exit: Sortie
 delete: Supprimer
+
+human_time:
+  after_days: !!pl
+    1: dans une jour
+    n: dans %1 jours
+  tomorrow: demain
+  after_hours: !!pl
+    1: dans une heure
+    n: dans %1 heures
+  after_minutes: !!pl
+    1: dans une minute
+    n: dans %1 minutes
+  now: maintenant
+  today: "aujourd'hui"
+  minutes_ago: !!pl
+    1: il ya une minute
+    n: il ya %1 minutes
+  hours_ago: !!pl
+    1: il ya une heure
+    n: il ya %1 heures
+  yesterday: hier
+  days_ago: !!pl
+    1: il ya une jour
+    n: il ya %1 jours

data/base/pl.yml

@@ -5,3 +5,27 @@ yes: Tak
 no: Nie
 exit: Wyjście
 delete: Usuń
+
+human_time:
+  after_days: !!pl
+    1: po %1 dniu
+    n: po %1 dniach
+  tomorrow: jutro
+  after_hours: !!pl
+    1: po %1 godzinie
+    n: po %1 godzinach
+  after_minutes: !!pl
+    1: po %1 minucie
+    n: po %1 minutach
+  now: teraz
+  today: dzisiaj
+  minutes_ago: !!pl
+    1: %1 minutę temu
+    n: %1 minut temu
+  hours_ago: !!pl
+    1: %1 godzinę temu
+    n: %1 godzin temu
+  yesterday: wczoraj
+  days_ago: !!pl
+    1: %1 dzień temu
+    n: %1 dni temu

data/base/ru.yml

@@ -5,3 +5,33 @@ yes: Да
 no: Нет
 exit: Выход
 delete: Удалить
+
+human_time:
+  after_days: !!pl
+    1: через %1 день
+    2: через %1 дня
+    n: через %1 дней
+  tomorrow: завтра
+  after_hours: !!pl
+    1: через %1 час
+    2: через %1 часа
+    n: через %1 часов
+  after_minutes: !!pl
+    1: через %1 минуту
+    2: через %1 минуты
+    n: через %1 минут
+  now: сейчас
+  today: сегодня
+  minutes_ago: !!pl
+    1: %1 минуту назад
+    2: %1 минуты назад
+    n: %1 минут назад
+  hours_ago: !!pl
+    1: %1 час назад
+    2: %1 часа назад
+    n: %1 часов назад
+  yesterday: вчера
+  days_ago: !!pl
+    1: %1 день назад
+    2: %1 дня назад
+    n: %1 дней назад

data/lib/r18n-core/filters.rb

@@ -0,0 +1,245 @@
+# encoding: utf-8
+=begin
+Filters for translations content.
+
+Copyright (C) 2009 Andrey “A.I.” Sitnik <andrey@sitnik.ru>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+=end
+
+require 'rubygems'
+    
+module R18n
+  # Filter is a way, to process translations: escape HTML entries, convert from
+  # Markdown syntax, etc.
+  # 
+  # In translation file filtered content must be marked by YAML type:
+  # 
+  #   filtered: !!custom_type
+  #     This content will be processed by filter
+  # 
+  # Filter function will be receive filtered content as first argument, struct
+  # with filter config as second and filter parameters as next arguments.
+  # 
+  #   R18n::Filters.add('custom_type', :no_space) do |content, config, replace|
+  #     content.gsub(' ', replace)
+  #   end
+  #   R18n::Filters.add('custom_type') do |content, config, replace|
+  #     content + '!'
+  #   end
+  #   
+  #   i18n.filtered('_') #=> "This_content_will_be_processed_by_filter!"
+  # 
+  # Use String class as type to add global filter for all translated strings:
+  # 
+  #   R18n::Filters.add(String, :escape_html) do |content, config, params|
+  #     escape_html(content)
+  #   end
+  #
+  # Filter config contain two parameters: translation locale and path. But it is
+  # 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
+  #     
+  #     if content.scan(CENSORSHIP_WORDS[config.locale]).empty?
+  #       content
+  #     else
+  #       "Error in #{config.path}"
+  #     end
+  #   end
+  #   
+  #   R18n::Filters.add('passed', :show_lie) do |content, config|
+  #     config.censorship_check = true
+  #     content
+  #   end
+  # 
+  # You can disable, enabled and delete filters:
+  # 
+  #   R18n::Filters.off(:no_space))
+  #   i18n.filtered('_') #=> "This content will be processed by filter!"
+  #   R18n::Filters.on(:no_space)
+  #   i18n.filtered('_') #=> "This_content_will_be_processed_by_filter!"
+  #   R18n::Filters.delete(:no_space)
+  module Filters
+    Filter = Struct.new(:name, :type, :block, :enabled) do
+      def call(*params)
+        block.call(*params)
+      end
+      
+      def enabled?
+        enabled
+      end
+    end
+    
+    class << self
+      # Hash of filter names to Filters.
+      def defined
+        @defined ||= {}
+      end
+      
+      # Hash of types to enabled Filters.
+      def enabled
+        @enabled ||= Hash.new([])
+      end
+      
+      # Hash of types to all Filters.
+      def by_type
+        @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)
+        
+        if type
+          filters = Filters.enabled[type]
+          filters.each { |f| translation = f.call(translation, config, *params)}
+        end
+        
+        if translation.is_a? String
+          Filters.enabled[String].each do |f|
+            translation = f.call(translation, config, *params)
+          end
+          return TranslatedString.new(translation, locale, path)
+        else
+          translation
+        end
+      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.
+      # 
+      # Several filters for same type will be call consecutively, but you can
+      # set +position+ in call list.
+      # 
+      # Filter content will be sent to +block+ as first argument, struct with
+      # config as second and filters parameters will be in next arguments.
+      def add(type, name = nil, position = nil, &block)
+        unless name
+          @last_auto_name ||= 0
+          begin
+            @last_auto_name += 1
+            name = @last_auto_name
+          end while defined.has_key? name
+        else
+          delete(name)
+        end
+        
+        filter = Filter.new(name, type, block, true)
+        defined[name] = filter
+        
+        unless enabled.has_key? type
+          enabled[type] = []
+          by_type[type] = []
+        end
+        if position
+          enabled[type].insert(position, filter)
+          by_type[type].insert(position, filter)
+        else
+          enabled[type] << filter
+          by_type[type] << defined[name]
+        end
+        
+        filter
+      end
+      
+      # Delete +filter+ by name or Filter object.
+      def delete(filter)
+        filter = defined[filter] unless filter.is_a? Filter
+        return unless filter
+        
+        defined.delete(filter.name)
+        by_type[filter.type].delete(filter)
+        enabled[filter.type].delete(filter)
+      end
+      
+      # Disable +filter+ by name or Filter object.
+      def off(filter)
+        filter = defined[filter] unless filter.is_a? Filter
+        return unless filter
+        
+        filter.enabled = false
+        enabled[filter.type].delete(filter)
+      end
+      
+      # Turn on disabled +filter+ by name or Filter object.
+      def on(filter)
+        filter = defined[filter] unless filter.is_a? Filter
+        return unless filter
+        
+        filter.enabled = true
+        enabled[filter.type] = by_type[filter.type].reject { |i| !i.enabled? }
+      end
+    end
+  end
+  
+  Filters.add('proc', :procedure) do |content, config, *params|
+    eval("proc { #{content} }").call(*params)
+  end
+  
+  Filters.add('pl', :pluralization) do |content, config, param|
+    type = config.locale.pluralize(param)
+    type = 'n' if not content.include? type
+    content[type]
+  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
+    end
+    content
+  end
+  
+  Filters.add('escape', :escape_html) do |content, config|
+    config.dont_escape_html = true
+    Utils.escape_html(content)
+  end
+  
+  Filters.add('html', :dont_escape_html) do |content, config|
+    config.dont_escape_html = true
+    content
+  end
+  
+  Filters.add(String, :global_escape_html) do |content, config|
+    if config.dont_escape_html
+      content
+    else
+      Utils.escape_html(content)
+    end
+  end
+  Filters.off(:global_escape_html)
+  
+  Filters.add('markdown', :maruku) do |content, config|
+    require 'maruku'
+    ::Maruku.new(content).to_html
+  end
+  
+  Filters.add('textile', :redcloth) do |content, config|
+    require 'redcloth'
+    ::RedCloth.new(content).to_html
+  end
+end