r18n-core 0.4.14 → 1.0.0

data/.yardopts

@@ -1,4 +1,4 @@
 --charset utf-8
 -
-README.rdoc
+README.md
 ChangeLog

data/ChangeLog

@@ -1,3 +1,24 @@
+== 1.0.0 (Bangkok)
+* Add R18n.default_places.
+* Rails SafeBuffer support.
+* Allow in Rails app to put filters to app/i18n reload them in development.
+* Move R18n::I18n.available_locales to R18n.available_locales.
+* Rename _keys to translation_keys.
+* Use Kramdown instead of Maruku for Markdown.
+* Allow to use R18n for Rails without mailer.
+* Allow to overwrite I18n object for models.
+* Autoload R18n::Translated.
+* Set default locale to R18n on Rails start to easy use in Rails console.
+* Use env language in Rails console.
+* Mark untranslated part as red in Rails console.
+* Allow to temporary change locale by R18n.change.
+* Add R18n.locale shortcut.
+* Allow return from setter block locale code, instead of I18n object.
+* Allow to set custom filters for I18n object.
+* Add Galician locale (by Eduard Giménez).
+* Add Traditional Chinese and Simplified Chinese (by Francis Chong).
+* Fix Norsk locale (by Peter Haza).
+
 == 0.4.14 (üç)
 * Fix support for Ruby 1.9.3.
 * Added Turkish locale (by Ahmet Özkaya).

data/LICENSE

@@ -10,7 +10,7 @@
 the terms and conditions of version 3 of the GNU General Public
 License, supplemented by the additional permissions listed below.
 
-  0. Additional Definitions. 
+  0. Additional Definitions.
 
   As used herein, "this License" refers to version 3 of the GNU Lesser
 General Public License, and the "GNU GPL" refers to version 3 of the GNU
@@ -111,7 +111,7 @@ the following:
        a copy of the Library already present on the user's computer
        system, and (b) will operate properly with a modified version
        of the Library that is interface-compatible with the Linked
-       Version. 
+       Version.
 
    e) Provide Installation Information, but only if you would otherwise
    be required to provide such information under section 6 of the

data/README.md

@@ -0,0 +1,456 @@
+# R18n
+
+R18n is an i18n tool to translate your Ruby application into several languages.
+
+Use `r18n-rails` or `sinatra-r18n` to localize Web applications and
+`r18n-desktop` to localize desktop application.
+
+## Features
+
+* Nice Ruby-style syntax.
+* Filters.
+* Model Translation (or any Ruby object).
+* Autodetect user locales.
+* Flexible locales.
+* Total flexibility.
+
+See full features in [main README](https://github.com/ai/r18n/blob/master/README.md).
+
+## Usage
+
+To add i18n support to your app, you can use the particular plugin for your
+environment: `r18n-rails`, `sinatra-r18n` or `r18n-desktop`.
+
+If you develop you own plugin or want to use only core gem, you will need to
+set default translation places and current locale:
+
+```ruby
+R18n.default_places = 'path/to/translations'
+R18n.set('en')
+```
+
+You can use `R18n.t` to get translations and `R18n.l` to localize times and
+numbers. But more useful is to add helpers to fast access the R18n:
+
+```ruby
+include R18n::Helpers
+
+t.yes              #=> "Yes"
+l Time.now, :human #=> "now"
+
+r18n.locale.code   #=> "en"
+```
+
+To set locale only for current thread use `R18n.thread_set`.
+
+### Translation
+
+Translation files are in YAML format by default and have names like
+`en.yml` (English) or `en-us.yml` (USA English dialect) with
+language/country code (RFC 3066).
+
+In your translation files you can use:
+
+* Strings
+
+    ```yaml
+    robot: This is a robot
+    percent: "Percent sign (%)"
+    ```
+
+* Numbers
+
+    ```yaml
+    number: 123
+    float: 12.45
+    ```
+
+* Pluralizable messages
+
+    ```yaml
+    robots: !!pl
+      0: No robots
+      1: One robot
+      n: %1 robots
+    ```
+
+* Filters
+
+    ```yaml
+    filtered: !!custom_type
+      This content will be processed by a filter
+    ```
+
+To get the translated string use a method with the key name or square brackets
+[] for keys, which is the same with Object methods (`class`, `inspect`, etc):
+
+```ruby
+t.robot    #=> "This is a robot"
+t[:robot]  #=> "This is a robot"
+```
+
+Translation may be hierarchical:
+
+```ruby
+t.post.add     #=> "Add post"
+t[:post][:add] #=> "Add post"
+```
+
+If the locale isn’t found in the user’s requested locale, R18n will search for
+it in sublocales or in another locale, which the user also can accept:
+
+```ruby
+t.not.in.english #=> "В английском нет"
+```
+
+The translated string has a `locale` method for determining its locale (Locale
+instance or code string if locale is’t supported in R18n):
+
+```ruby
+i18n.not.in.english.locale #=> Locale ru (Русский)
+```
+
+You can include parameters in the translated string by specifying arguments:
+
+```yaml
+name: My name is %1
+```
+
+```ruby
+t.name('John') #=> "My name is John"
+```
+
+Pluralizable messages get their item count from the first argument:
+
+```ruby
+t.robots(0)  #=> "No robots"
+t.robots(1)  #=> "One robot"
+t.robots(50) #=> "50 robots"
+```
+
+If there isn’t a pluralization for a particular number, translation will be use
+`n`. If there isn’t a locale file for translation, it will use the English
+pluralization rule (`0`, `1` and `n`).
+
+You can check if the key has a translation:
+
+```ruby
+t.post.add.translated?   #=> true
+t.not.exists.translated? #=> false
+```
+
+You can set a default value for untranslated strings:
+
+```ruby
+t.not.exists | 'default' #=> "default"
+```
+
+You can query the translation keys:
+
+```ruby
+t.counties.translation_keys.each do |county|
+  puts t.counties[county]
+end
+```
+
+R18n already has translations for common words for most built in locales.
+See `base/` the source.
+
+```ruby
+t.yes    #=> "Yes"
+t.cancel #=> "Cancel"
+t.delete #=> "Delete"
+```
+
+### Filters
+
+You can also add you own filters for translations: escape HTML entities, convert
+from Markdown syntax, etc. Filters can be passive, only being processed when
+loaded.
+
+```yaml
+friendship: !!gender
+  f: She adds a friend
+  m: He adds a friend
+```
+
+```ruby
+R18n::Filters.add('gender', :user_gender) do |content, config, user|
+  if user.female?
+    content['f']
+  else
+    content['m']
+  end
+end
+
+t.friendship(anne) #=> "She adds a friend"
+```
+
+To create a filter you pass the following to `R18n::Filters.add`:
+
+* Filter target. YAML type (`!!type`), `String` for all translations of
+  `R18n::Untranslated` for missing translations.
+* Optional filter name, to disable, enable or delete it later by
+  `R18n::Filters.off`, `R18n::Filters.on` and
+  `R18n::Filters.delete`.
+* Hash with options:
+  * `:passive => true` to filter translations only on load;
+  * `:position` within the list of current filters of this type
+    (by default a new filter will be inserted into last position).
+
+The filter will receive at least two arguments:
+* Translation (possibly already filtered by other filters for this type earlier
+  in the list).
+* A Hash with translation `locale` and `path`.
+* Parameters from translation request will be in the remaining arguments.
+
+#### HTML Escape
+
+R18n contains 2 filters to escape HTML entities: by YAML type and global. If you
+need to escape HTML in some translations, just set `!!escape` YAML type:
+
+```yaml
+greater: !!escape
+  1 < 2 is true
+```
+
+```ruby
+t.greater #=> "1 &lt; 2 is true"
+```
+
+If you develop web application and want to escape HTML in all translations, just
+activate the global escape filter:
+
+```ruby
+R18n::Filters.on(:global_escape_html)
+```
+
+If you enable global HTML escape, you may still use `!!html` YAML type to
+disable escaping on some values:
+
+```yaml
+warning: !!html
+  <b>Warning</b>
+```
+
+```ruby
+R18n::Filters.on(:global_escape_html)
+t.warning #=> "<b>Warning</b>"
+```
+
+#### Markdown
+
+To use Markdown in your translations you must install the Kramdown gem:
+
+```yaml
+hi: !!markdown
+  **Hi**, people!
+```
+
+```ruby
+t.hi #=> "<p><strong>Hi</strong>, people!</p>"
+```
+
+#### Textile
+
+To use Textile in your translations you must install the RedCloth gem:
+
+```yaml
+alarm: !!textile
+  It will delete _all_ users!
+```
+
+```ruby
+t.alarm #=> "<p>It will delete <em>all</em> users!</p>"
+```
+
+#### Lambdas
+
+You can use lambdas in your translations.
+
+```yaml
+sum: !!proc |x, y| x + y
+```
+
+```ruby
+t.sum(1, 2) #=> 3
+```
+
+If this is unsafe in your application (for example, user can change
+translations), you can disable it:
+
+```ruby
+R18n::Filters.off(:procedure)
+```
+
+### Localization
+
+You can print numbers and floats according to the rules of the user locale:
+
+```ruby
+l -12000.5 #=> "−12,000.5"
+```
+
+Number and float formatters will also put real typographic minus and put
+non-breakable thin spaces (for locale, which use it as digit separator).
+
+You can translate months and week day names in Time, Date and DateTime by the
+`strftime` method:
+
+```ruby
+l Time.now, '%B'  #=> "September"
+```
+
+R18n has some built-in time formats for locales: `:human`, `:full` and
+`:standard` (the default):
+
+```ruby
+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 (ActiveRecord,
+DataMapper, MongoMapper, Mongoid or others):
+
+```ruby
+class Product
+  include DataMapper::Resource
+  property :title_ru, String
+  property :title_en, String
+
+  include R18n::Translated
+  translations :title
+end
+
+# For example, user only knows Russian
+
+# Set English (default) title
+product.title_en = "Anthrax"
+product.title #=> "Anthrax"
+
+# Set value for user locale (Russian)
+product.title = "Сибирская язва"
+product.title #=> "Сибирская язва"
+
+product.title_en #=> "Anthrax"
+product.title_ru #=> "Сибирская язва"
+```
+
+See `R18n::Translated` for documentation.
+
+### Locale
+
+All supported locales are stored in R18n gem in `locales` directory. If you want
+to add your locale, please fork this project and send a pull request or email me
+at <andrey@sitnik.ru>.
+
+To get information about a locale create an `R18n::Locale` instance:
+
+```ruby
+locale = R18n.locale('en')
+```
+
+You can then get the following from the locale:
+
+* Locale title and RFC 3066 code:
+
+    ```ruby
+    locale.title #=> "English"
+    locale.code  #=> "en"
+    ```
+
+* Language direction (left to right, or right to left for Arabic and Hebrew):
+
+    ```ruby
+    locale.ltr? #=> true
+    ```
+
+* Week start day (`:monday` or `:sunday`):
+
+    ```ruby
+    locale.week_start #=> :sunday
+    ```
+
+### Loaders
+
+You can load translations from anywhere, not just from YAML files. To load
+translation you must create loader class with 2 methods:
+
+* `available` – return array of locales of available translations;
+* `load(locale)` – return Hash of translation.
+
+Pass its instance to `R18n.default_places` or `R18n.set(locales, loaders)`
+
+```ruby
+R18n.default_places = MyLoader.new(loader_param)
+R18n.set('en')
+```
+
+You can set your default loader and pass it to `R18n.set` as the only
+constructor argument:
+
+```ruby
+R18n.default_loader = MyLoader
+R18n.default_places = loader_param
+
+R18n.set('en')
+R18n.set('en', different_loader_param)
+```
+
+If you want to load a translation with some type for filter, use
+`R18n::Typed` struct:
+
+```ruby
+# Loader will return something like:
+{ 'users' => R18n::Typed.new('pl', { 1 => '1 user', 'n' => '%1 users' }) }
+
+# 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 directory. R18n contain translations for base words
+as extension directory too.
+
+```ruby
+R18n.extension_places << R18n::Loader::YAML.new('./error_messages/')
+```
+
+## Add Locale
+
+If R18n hasn’t got locale file for your language, please add it. It’s very
+simple:
+
+* Create the file <tt><i>code</i>.rb</tt> in the `locales/` directory for your
+  language and describe locale. Just copy from another locale and change the
+  values.
+  * If your country has alternate languages (for example, in exUSSR countries
+    most people also know Russian), add
+    <tt>sublocales %w{<i>another_locale</i> en}</tt>.
+* Create in `base/` file <tt><i>code</i>.yml</tt>  for your language and
+  translate the base messages. Just copy file from language, which you know,
+  and rewrite values.
+* If your language needs some special logic (for example, different
+  pluralization or time formatters) you can extend `R18n::Locale` class methods.
+* Send a pull request via GitHub <http://github.com/ai/r18n> or just write email
+  with the 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). Email me with any questions you may have, you will
+find other contact addresses at http://sitnik.ru.
+
+## License
+
+R18n is licensed under the GNU Lesser General Public License version 3.
+See the LICENSE file or http://www.gnu.org/licenses/lgpl.html.
+
+## Author
+
+Andrey “A.I.” Sitnik <andrey@sitnik.ru>

data/Rakefile

@@ -27,7 +27,8 @@ YARD::Rake::YardocTask.new do |yard|
 end
 
 task :clobber_doc do
-  rm_r 'doc' rescue nil
+  rm_r 'doc'     rescue nil
+  rm_r '.yardoc' rescue nil
 end
 task :clobber_package do
   rm_r 'pkg' rescue nil

data/base/gl.yml

@@ -0,0 +1,31 @@
+ok: 'OK'
+save: 'Gardar'
+cancel: 'Cancelar'
+'yes': 'Sí'
+'no': 'Non'
+exit: 'Deixar'
+delete: 'Borrar'
+
+human_time:
+  after_days: !!pl
+    1: 'despois do %1 día'
+    n: 'tras %1 días'
+  tomorrow: 'mañá'
+  after_hours: !!pl
+    1: 'despois de %1 hora'
+    n: 'tras %1 horas'
+  after_minutes: !!pl
+    1: 'despois de %1 minuto'
+    n: 'tras %1 minutos'
+  now: 'agora'
+  today: 'hoxe'
+  minutes_ago: !!pl
+    1: '%1 minuto'
+    n: '%1 minutos'
+  hours_ago: !!pl
+    1: '%1 hora'
+    n: '%1 horas'
+  yesterday: 'ayer'
+  days_ago: !!pl
+    1: '%1 día'
+    n: '%1 días'

data/base/it.yml

@@ -5,7 +5,7 @@ cancel: 'Annulla'
 'no': 'No'
 exit: 'Esci'
 delete: 'Cancella'
- 
+
 human_time:
   after_days: !!pl
     1: 'dopo %1 giorno'

data/lib/r18n-core/filter_list.rb

@@ -0,0 +1,157 @@
+# encoding: utf-8
+=begin
+Filters for translations content.
+
+Copyright (C) 2012 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
+  # Superclass for +GlobalFilterList+ and +CustomFilterList+ with filters
+  # processing.
+  class FilterList
+    # Process +value+ by filters in +enabled+.
+    def process(filters_type, type, value, locale, path, params)
+      config = { :locale => locale, :path => path }
+
+      enabled(filters_type, type).each do |filter|
+        value = filter.call(value, config, *params)
+      end
+
+      if value.is_a? String
+        value = TranslatedString.new(value, locale, path)
+        process_string(filters_type, value, config, params)
+      else
+        value
+      end
+    end
+
+    # Shortcut ot process `R18n::Typed`.
+    def process_typed(filters_type, typed_value, params)
+      process(filters_type,
+              typed_value.type,
+              typed_value.value,
+              typed_value.locale,
+              typed_value.path,
+              params)
+    end
+
+    # Process +value+ by global filters in +enabled+.
+    def process_string(filters_type, value, config, params)
+      if config.is_a? String
+        config = { :locale => value.locale, :path => config }
+      end
+      enabled(filters_type, String).each do |f|
+        value = f.call(value, config, *params)
+      end
+      value
+    end
+
+    # Array of enabled filters with +filters_type+ for +type+.
+    def enabled(filters_type, type)
+      if filters_type == :passive
+        passive(type)
+      elsif filters_type == :active
+        active(type)
+      else
+        all(type)
+      end
+    end
+
+    # List of enable passive filters.
+    def passive(type)
+      []
+    end
+
+    # List of enable active filters.
+    def active(type)
+      []
+    end
+
+    # List of enable filters.
+    def all(type)
+      []
+    end
+  end
+
+  # Filter list for I18n object with only global filters.
+  class GlobalFilterList < FilterList
+    include Singleton
+
+    def passive(type)
+      Filters.passive_enabled[type]
+    end
+
+    def active(type)
+      Filters.active_enabled[type]
+    end
+
+    def all(type)
+      Filters.enabled[type]
+    end
+  end
+
+  # Filter list for I18n object with custom disabled/enabled filters.
+  class CustomFilterList < FilterList
+
+    def initialize(on, off)
+      @on  = Array(on).map  { |i| Filters.defined[i] }
+      @off = Array(off).map { |i| Filters.defined[i] }
+      @changed_types = (@on + @off).map { |i| i.types }.flatten.uniq
+
+      @changed_passive = (@on + @off).reject { |i| !i.passive? }.
+        map { |i| i.types }.flatten.uniq
+      @changed_active  = (@on + @off).reject { |i|  i.passive? }.
+        map { |i| i.types }.flatten.uniq
+
+      @on_by_type = {}
+      @on.each do |filter|
+        filter.types.each do |type|
+          @on_by_type[type] ||= []
+          @on_by_type[type] << filter
+        end
+      end
+      @off_by_type = {}
+      @off.each do |filter|
+        filter.types.each do |type|
+          @off_by_type[type] ||= []
+          @off_by_type[type] << filter
+        end
+      end
+    end
+
+    def passive(type)
+      enabled = Filters.passive_enabled[type]
+      return enabled unless @changed_passive.include? type
+      enabled  = enabled.reject { |i| @off_by_type[type].include? i }
+      enabled += @on_by_type[type].reject { |i| !i.passive }
+    end
+
+    def active(type)
+      enabled = Filters.active_enabled[type]
+      return enabled unless @changed_active.include? type
+      enabled  = enabled.reject { |i| @off_by_type[type].include? i }
+      enabled += @on_by_type[type].reject { |i|  i.passive }
+    end
+
+    def all(type)
+      enabled = Filters.enabled[type]
+      return enabled unless @changed_types.include? type
+      enabled  = enabled.reject { |i| @off_by_type[type].include? i }
+      enabled += @on_by_type[type]
+    end
+
+  end
+end