r18n-core 0.1

data/lib/r18n-core/i18n.rb

@@ -0,0 +1,191 @@
+=begin
+I18n support.
+
+Copyright (C) 2008 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 'date'
+
+module R18n
+  # General class to i18n support in your application. It load Translation and
+  # Locale classes and create pretty way to use it.
+  #
+  # To get translation you can use same with Translation way – use method with
+  # translation’s name or <tt>[name]</tt> method. Translations will be also
+  # loaded for default locale, +sublocales+ from first in +locales+ and general
+  # languages for dialects (it will load +fr+ for +fr_CA+ too).
+  #
+  # See Translation and Locale documentation.
+  #
+  # == Usage
+  # translations/ru.yml
+  #
+  #   one: Один
+  #
+  # translations/en.yml
+  #
+  #   one: One
+  #   two: Two
+  #
+  # example.rb
+  # 
+  #   i18n = R18n::I18n.new(['ru', 'en'], 'translations/')
+  #   
+  #   i18n.one   #=> "Один"
+  #   i18n.two   #=> "Two"
+  #   
+  #   i18n.locale['title']     #=> "Русский"
+  #   i18n.locale['code']      #=> "ru"
+  #   i18n.locale['direction'] #=> "ltr"
+  #   
+  #   i18n.l -11000.5          #=> "−11 000,5"
+  #   i18n.l Time.now          #=> "Вск, 21 сен 2008, 22:10:10 MSD"
+  #   i18n.l Time.now, :date   #=> "21.09.2008"
+  #   i18n.l Time.now, :time   #=> "22:10"
+  #   i18n.l Time.now, '%A'    #=> "Воскресенье"
+  class I18n
+    @@default = 'en'
+
+    # Set default locale code to use when any user locales willn't be founded.
+    # It should has all translations and locale file.
+    def self.default=(locale)
+      @@default = locale
+    end
+
+    # Get default locale code
+    def self.default
+      @@default
+    end
+    
+    # Parse HTTP_ACCEPT_LANGUAGE and return array of user locales
+    def self.parse_http(str)
+      return [] if str.nil?
+      locales = str.split(',')
+      locales.map! do |locale|
+        locale = locale.split ';q='
+        if 1 == locale.size
+          [locale[0], 1.0]
+        else
+          [locale[0], locale[1].to_f]
+        end
+      end
+      locales.sort! { |a, b| b[1] <=> a[1] }
+      locales.map! { |i| i[0] }
+    end
+    
+    # User locales, ordered by priority
+    attr_reader :locales
+    
+    # Dir with translations files
+    attr_reader :translations_dir
+    
+    # First locale with locale file
+    attr_reader :locale
+    
+    # Create i18n for +locales+ with translations from +translations_dir+ and
+    # locales data. Translations will be also loaded for default locale,
+    # +sublocales+ from first in +locales+ and general languages for dialects
+    # (it will load +fr+ for +fr_CA+ too).
+    #
+    # +Locales+ must be a locale code (RFC 3066) or array, ordered by priority.
+    def initialize(locales, translations_dir)
+      locales = locales.to_a if String == locales.class
+      
+      @locales = locales.map do |locale|
+        if Locale.exists? locale
+          Locale.new locale
+        else
+          locale
+        end
+      end
+      
+      locales << @@default
+      if Locale == @locales.first.class
+        locales += @locales.first['sublocales']
+      end
+      locales.each_with_index do |locale, i|
+        if "_" == locale[2..2]
+          locales.insert(i + 1, locale[0..1])
+        end
+      end
+      locales.uniq!
+      
+      locales.each do |locale|
+        if Locale.exists? locale
+          @locale = Locale.new(locale)
+          break
+        end
+      end
+      
+      @translations_dir = File.expand_path(translations_dir)
+      @translation = Translation.load(locales, @translations_dir)
+    end
+    
+    # Return Hash with titles (or code for translation without locale file) of
+    # available translations.
+    def translations
+      Translation.available(@translations_dir).inject({}) do |all, code|
+        all[code] = if Locale.exists? code
+          Locale.new(code)['title']
+        else
+          code
+        end
+        all
+      end
+    end
+    
+    # Convert +object+ to String, according to the rules of the current locale.
+    # It support Fixnum, Bignum, Float, Time, Date and DateTime.
+    #
+    # For time classes you can set +format+ in standart +strftime+ form, or
+    # Symbol to use format from locale file (<tt>:time</tt>, <tt>:date</tt>,
+    # <tt>:short_data</tt>, <tt>:long_data</tt>, <tt>:datetime</tt>,
+    # <tt>:short_datetime</tt> or <tt>:long_datetime</tt>). Without format it
+    # use <tt>:datetime</tt> for Time and DateTime and <tt>:date</tt> for Date.
+    def localize(object, format = nil)
+      if Fixnum == object.class or Bignum == object.class
+        locale.format_number(object)
+      elsif Float == object.class
+        locale.format_float(object)
+      elsif Time == object.class or DateTime == object.class
+        format = :datetime if format.nil?
+        locale.strftime(object, format)
+      elsif Date == object.class
+        format = :date if format.nil?
+        locale.strftime(object, format)
+      end
+    end
+    alias :l :localize
+    
+    # Short and pretty way to get translation by method name. If translation
+    # has name like object methods (+new+, +to_s+, +methods+) use <tt>[]</tt>
+    # method to access.
+    #
+    # Translation can contain variable part. Just set is as <tt>%1</tt>,
+    # <tt>%2</tt>, etc in translations file and set values as methods params.
+    def method_missing(name, *params)
+      self[name.to_s, *params]
+    end
+    
+    # Return translation with special +name+.
+    #
+    # Translation can contain variable part. Just set is as <tt>%1</tt>,
+    # <tt>%2</tt>, etc in translations file and set values in next +params+.
+    def [](name, *params)
+      @translation[name, *params]
+    end
+  end
+end

data/lib/r18n-core/locale.rb

@@ -0,0 +1,171 @@
+=begin
+Locale to i18n support.
+
+Copyright (C) 2008 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 'pathname'
+require 'yaml'
+
+module R18n
+  # Information about locale (language, country and other special variant
+  # preferences). Locale was named by RFC 3066. For example, locale for French
+  # speaking people in Canada will be +fr_CA+.
+  #
+  # Locale files is placed in <tt>locales/</tt> dir in YAML files.
+  #
+  # Each locale has +sublocales+ – often known languages for people from this
+  # locale. For example, many Belorussians know Russian and English. If there
+  # is’t translation for Belorussian, it will be searched in Russian and next in
+  # English translations.
+  #
+  # == Usage
+  #
+  # Get Russian locale and print it information
+  #
+  #   ru = R18n::Locale.new('ru')
+  #   ru['title']        #=> "Русский"
+  #   ru['code']         #=> "ru"
+  #   ru['direction']    #=> "ltr"
+  #
+  # == Available data
+  #
+  # * +code+: locale RFC 3066 code;
+  # * +title+: locale name on it language;
+  # * +direction+: writing direction, +ltr+ or +rtl+ (for Arabic and Hebrew);
+  # * +sublocales+: often known languages for people from this locale;
+  # * +pluralization+: function to get pluralization type for +n+ items;
+  # * +include+: locale code to include it data, optional.
+  #
+  # You can see more available data about locale in samples in
+  # <tt>locales/</tt> dir.
+  class Locale
+    LOCALES_DIR = Pathname(__FILE__).dirname.expand_path + '../../locales/'
+
+    # All available locales
+    def self.available
+      Dir.glob(LOCALES_DIR + '*.yml').map do |i|
+        File.basename(i, '.yml')
+      end
+    end
+    
+    # Is +locale+ has info file
+    def self.exists?(locale)
+      File.exists?(File.join(LOCALES_DIR, locale + '.yml'))
+    end
+    
+    # Default pluralization rule to translation without locale file
+    def self.default_pluralize(n)
+      n == 0 ? 0 : n == 1 ? 1 : 'n'
+    end
+
+    # Load locale by RFC 3066 +code+
+    def initialize(code)
+      code.delete! '/'
+      code.delete! '\\'
+      
+      @locale = {}
+      while code
+        file = LOCALES_DIR + "#{code}.yml"
+        raise "Locale #{code} isn't exists" if not File.exists? file
+        loaded = YAML.load_file(file)
+        @locale = loaded.merge @locale
+        code = loaded['include']
+      end
+      
+      eval("def pluralize(n); #{@locale["pluralization"]}; end", binding)
+    end
+
+    # Get information about locale
+    def [](name)
+      @locale[name]
+    end
+
+    # Is another locale has same code
+    def ==(locale)
+      @locale['code'] == locale['code']
+    end
+
+    # Human readable locale code and title
+    def inspect
+      "Locale #{@locale['code']} (#{@locale['title']})"
+    end
+    
+    # Returns the integer in String form, according to the rules of the locale.
+    # It will also put real typographic minus.
+    def format_number(number)
+      str = number.to_s
+      str[0] = '−' if 0 > number # Real typographic minus
+      group = @locale['numbers']['group_delimiter']
+      
+      if 'indian' == @locale['numbers']['separation']
+        str.gsub(/(\d)(?=((\d\d\d)(?!\d))|((\d\d)+(\d\d\d)(?!\d)))/) do |match|
+          match + group
+        end
+      else
+        str.gsub(/(\d)(?=(\d\d\d)+(?!\d))/) do |match|
+          match + group
+        end
+      end
+    end
+    
+    # Returns the float in String form, according to the rules of the locale.
+    # It will also put real typographic minus.
+    def format_float(float)
+      decimal = @locale['numbers']['decimal_separator']
+      self.format_number(float.to_i) + decimal + float.to_s.split('.').last
+    end
+    
+    # Same that <tt>Time.strftime</tt>, but translate months and week days
+    # names. In +time+ you can use Time, DateTime or Date object. In +format+
+    # you can use String with standart +strftime+ format (see
+    # <tt>Time.strftime</tt> docs) or Symbol with format from locale file
+    # (<tt>:time</tt>, <tt>:date</tt>, <tt>:short_data</tt>, <tt>:long_data</tt>,
+    # <tt>:datetime</tt>, <tt>:short_datetime</tt> or <tt>:long_datetime</tt>).
+    def strftime(time, format)
+      if Symbol == format.class
+        format = @locale['formats'][format.to_s]
+      end
+      
+      translated = ''
+      format.scan(/%[EO]?.|./o) do |c|
+        case c.sub(/^%[EO]?(.)$/o, '%\\1')
+        when '%A'
+          translated << @locale['week']['days'][time.wday]
+        when '%a'
+          translated << @locale['week']['abbrs'][time.wday]
+        when '%B'
+          translated << @locale['months']['names'][time.month - 1]
+        when '%b'
+          translated << @locale['months']['abbrs'][time.month - 1]
+        when '%p'
+          translated << if time.hour < 12
+            @locale['time']['am']
+          else
+            @locale['time']['pm']
+          end
+        else
+          translated << c
+        end
+      end
+      time.strftime(translated)
+    end
+
+    # Return pluralization type for +n+ items. It will be replacing by code
+    # from locale file.
+    def pluralize(n); end
+  end
+end

data/lib/r18n-core/translated_string.rb

@@ -0,0 +1,33 @@
+=begin
+Translation string for i18n support.
+
+Copyright (C) 2008 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
+
+module R18n
+  # String, which is translated to some locale and loading from Translation.
+  class TranslatedString < String
+    # String locale
+    attr_reader :locale
+    
+    # Returns a new string object containing a copy of +str+, which translated
+    # to +locale+
+    def initialize(str, locale)
+      super(str)
+      @locale = locale
+    end
+  end
+end

data/lib/r18n-core/translation.rb

@@ -0,0 +1,203 @@
+=begin
+Translation to i18n support.
+
+Copyright (C) 2008 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 'pathname'
+require 'yaml'
+
+module R18n
+  # Translation for interface to i18n support. You can load several locales and
+  # if translation willn’t be found in first, r18n will be search it in next.
+  #
+  # 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). In
+  # translation file you can use strings, numbers, floats (any YAML types),
+  # procedures (<tt>!!proc</tt>) and pluralizable values (<tt>!!pl</tt>). You
+  # can use params in string values, which you can replace in program. Just
+  # write <tt>%1</tt>, <tt>%2</tt>, etc and set it values as method arguments,
+  # when you will be get value.
+  #
+  # To get translation value use method with same name. If translation name
+  # is equal with Object methods (+new+, +to_s+, +methods+) use
+  # <tt>[name, params…]</tt>. If you want to get pluralizable value, just set
+  # value for pluralization in fisrt argument of method. See samples below.
+  #
+  # Translated strings will have +locale+ methods, which return Locale or it
+  # code, if locale file isn’t exists.
+  #
+  # R18n contain translations for common words (such as “OK”, “Cancel”, etc)
+  # for most supported locales. See <tt>base/</tt> dir.
+  #
+  # == Examples
+  # translations/ru.yml
+  #
+  #   one: Один
+  #
+  # translations/en.yml
+  #
+  #   one: One
+  #   two: Two
+  #   
+  #   entry:
+  #     between: Between %1 and %2
+  #   methods: Is %1 method
+  #   
+  #   comments: !!pl
+  #     0: no comments
+  #     1: one comment
+  #     n: %1 comments
+  #
+  #   sum: !!proc |x, y| "is #{x + y}"
+  #
+  # example.rb
+  #
+  #   i18n = R18n::Translation.load(['ru', 'en'], 'translations/')
+  #   i18n.one   #=> "Один"
+  #   i18n.two   #=> "Two"
+  #   
+  #   i18n.two.locale['code']      #=> "en"
+  #   i18n.two.locale['direction'] #=> "ltr"
+  #
+  #   i18n.entry.between(2, 3)    #=> "between 2 and 3"
+  #   i18n['methods', 'object']   #=> "Is object method"
+  #   
+  #   i18n.comments(0)            #=> "no comments"
+  #   i18n.comments(10)           #=> "10 comments"
+  #   
+  #   i18n.sum(2, 3) #=> "is 5"
+  #
+  #   i18n.yes    #=> "Yes"
+  #   i18n.ok     #=> "OK"
+  #   i18n.cancel #=> "Cancel"
+  #
+  # == Extension translations
+  # For r18n plugin you can add dir 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.
+  class Translation
+    @@extension_translations = [
+      Pathname(__FILE__).dirname.expand_path + '../../base']
+
+    # Get dirs with extension translations. If application translations with
+    # same locale isn’t exists, extension file willn’t be used.
+    def self.extension_translations
+      @@extension_translations
+    end
+    
+    # Return available translations in +translations_dir+
+    def self.available(translations_dir)
+      Dir.glob(File.join(translations_dir, '*.yml')).map do |i|
+        File.basename(i, '.yml')
+      end
+    end
+
+    # Load all available translations for +locales+. +locales+ may be string
+    # with one user locale or array with many.
+    def self.load(locales, translations_dir)
+      locales = locales.to_a if Array != locales.class
+      
+      locales &= self.available(translations_dir)
+      
+      translations = []
+      locales.map! do |locale|
+        translation = {}
+        @@extension_translations.each do |dir|
+          file = File.join(dir, "#{locale}.yml")
+          translation.merge! YAML::load_file(file) if File.exists? file
+        end
+        file = File.join(translations_dir, "#{locale}.yml")
+        translation.merge! YAML::load_file(file)
+        translations << translation
+        
+        if Locale.exists? locale
+          Locale.new(locale)
+        else
+          locale
+        end
+      end
+  
+      self.new(locales, translations)
+    end
+    
+    # Create translation hash with messages in +translations+ for +locales+.
+    #
+    # This is internal a constructor. To load translation use
+    # <tt>R18n::Translation.load(locales, translations_dir)</tt>.
+    def initialize(locales, translations)
+      @locales = locales
+      @translations = translations
+    end
+    
+    # Short and pretty way to get translation by method name. If translation
+    # has name like object methods (+new+, +to_s+, +methods+) use <tt>[]</tt>
+    # method to access.
+    #
+    # Translation can contain variable part. Just set is as <tt>%1</tt>,
+    # <tt>%2</tt>, etc in translations file and set values as methods params.
+    def method_missing(name, *params)
+      self[name.to_s, *params]
+    end
+    
+    # Return translation with special +name+.
+    #
+    # Translation can contain variable part. Just set is as <tt>%1</tt>,
+    # <tt>%2</tt>, etc in translations file and set values in next +params+.
+    def [](name, *params)
+      @translations.each_with_index do |translation, i|
+        result = translation[name]
+        next if result.nil?
+        
+        if YAML::PrivateType == result.class
+          case result.type_id
+          when 'proc'
+            return eval("proc {#{result.value}}").call(*params)
+          when 'pl'
+            locale = @locales[i]
+            
+            type = if Locale == locale.class
+              locale.pluralize(params.first)
+            else
+              Locale.default_pluralize(params.first)
+            end
+            
+            type = 'n' if not result.value.include? type
+            result = result.value[type]
+          else
+            return result
+          end
+        end
+        
+        if String == result.class
+          params.each_with_index do |param, i|
+            result.gsub! "%#{i+1}", param.to_s
+          end
+          return TranslatedString.new(result, @locales[i])
+        elsif Hash == result.class
+          return self.class.new(@locales, @translations.map { |i|
+            i[name] or {}
+          })
+        else
+          return result
+        end
+      end
+      
+      return nil
+    end
+  end
+end