fast_gettext 1.8.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af7af45d00211da2791e03bf1f4f7c611d8c557a10f339189ebdf2a72008ff05
-  data.tar.gz: 23040ab7524d7eb95b0e11fcc22a05a1ddf54eeeb88babade01c9876620447c5
+  metadata.gz: 3b7df1ae6f9c9acae6fe82a22b0ce3efd1d545c9d814447070ebb59652a7fd71
+  data.tar.gz: 05af6efd5f93f5ea8bf2f8be7314566d0238781f7d809799823223ec01866ce4
 SHA512:
-  metadata.gz: c9152caffa285a723a4681e23db5d0710465a5b47f2c2251f863026cf91da316cdd36155097038896d77cb1c5562af619e73cf29f69be70bebec28ac8bf6d272
-  data.tar.gz: c59623e1c15a293922cfcdd457634a2cb5f082900ee0948d14d7d37c4ddac5533f1fa6437f8e9bc200cc391e9be4a8c6d416e72568017905f0be930fbd65bb00
+  metadata.gz: b0df4b37e9837b4661cf7c0cbef1c75144c3c2804b2da4110a4850c08eb3084a91cd419ffb5c796eff30ee96860d87cb555a3cb2bd3e99e25db64731868a08ff
+  data.tar.gz: dc6f882c3c3fa4ea1c3fc2399077d149c3e981124de8f9da99e0ee7bdf2fd248ac74131cc92f9167d05ef15a04eb2ba4e25780ea1f8bc9ecfe04795776704310

data/CHANGELOG

@@ -1,11 +1,12 @@
+2.0.0 -- Changed p_ separator to \0004 https://github.com/grosser/fast_gettext/pull/107 add np and add gettext aliases
 1.6.0 -- Remove restrictions around yaml file names
 1.1.0 -- translations are no longer eager loaded for improved startup performance, pass `eager_load: true` to preload for example in preforked web server
 1.0.0 -- do not enforce attr_accessible unless ProtectedAttributes are loaded
-0.9.0 -- reworked internals of caching to be plugable
+0.9.0 -- reworked internals of caching to be pluggable
 0.7.0 -- set_locale resets to default locale if none of the available locales was tried to set
-0.6.0 -- plurals use singular translations as fallack e.g. you translated 'Axis' then n_('Axis','Axis',1) would return the translation for 'Axis' if no plural translation was found
+0.6.0 -- plurals use singular translations as fallback e.g. you translated 'Axis' then n_('Axis','Axis',1) would return the translation for 'Axis' if no plural translation was found
 0.4.14 -- "" is translated as "", not as gettext meta information
-0.4.0 -- pluralisation_rules is no longer stored in each repository, only retrived. Added Chain and Logger repository.
+0.4.0 -- pluralisation_rules is no longer stored in each repository, only retrieved. Added Chain and Logger repository.
 0.3.6 -- FastGettext.default_locale=
 0.3.5 -- FastGettext.default_text_domain=
 0.3.4 -- Exceptions are thrown, not returned when translating without text domain

data/Readme.md

@@ -1,11 +1,12 @@
 FastGettext
 ===========
-GetText but 3.5 x faster, 560 x less memory, simple, clean namespace (7 vs 34) and threadsafe!
+GetText but 12 x faster, 530 x less garbage, clean namespace (8 vs 26), simple and threadsafe!
 
 It supports multiple backends (.mo, .po, .yml files, Database(ActiveRecord + any other), Chain, Loggers) and can easily be extended.
 
 [Example Rails application](https://github.com/grosser/gettext_i18n_rails_example)
 
+
 Comparison
 ==========
 <table>
@@ -18,17 +19,17 @@ Comparison
   </tr>
   <tr>
     <td>Speed*</td>
-    <td>0.82s</td>
-    <td>1.36s</td>
-    <td>4.88s</td>
-    <td>21.77s</td>
+    <td>0.08s</td>
+    <td>0.14s</td>
+    <td>1.75s</td>
+    <td>3.75s</td>
   </tr>
   <tr>
-    <td>RAM*</td>
-    <td>4K</td>
-    <td>8K</td>
-    <td>4480K</td>
-    <td>10100K</td>
+    <td>Objects*</td>
+    <td>11K</td>
+    <td>15K</td>
+    <td>8017K</td>
+    <td>7107K</td>
   </tr>
   <tr>
     <td>Included backends</td>
@@ -38,10 +39,12 @@ Comparison
     <td>yml (db/key-value/po/chain in other I18n backends)</td>
   </tr>
 </table>
-<small>*50.000 translations with ruby enterprise 1.8.6 through `rake benchmark`</small>
+<small>*500.000 translations with ruby 2.5.3 through `bundle exec rake benchmark`</small>
+
 
 Setup
 =====
+
 ### 1. Install
 
 ```Bash
@@ -60,8 +63,8 @@ Or po files (less maintenance than mo)
 
 ```Ruby
 FastGettext.add_text_domain('my_app', path: 'locale', type: :po)
-# :ignore_fuzzy => true to not use fuzzy translations
-# :report_warning => false to hide warnings about obsolete/fuzzy translations
+# ignore_fuzzy: true to not use fuzzy translations
+# report_warning: false to hide warnings about obsolete/fuzzy translations
 ```
 
 Or yaml files (use I18n syntax/indentation)
@@ -77,7 +80,7 @@ Or database (scaleable, good for many locales/translators)
 ```Ruby
 # db access is cached <-> only first lookup hits the db
 require "fast_gettext/translation_repository/db"
-FastGettext::TranslationRepository::Db.require_models #load and include default models
+FastGettext::TranslationRepository::Db.require_models # load and include default models
 FastGettext.add_text_domain('my_app', type: :db, model: TranslationKey)
 ```
 
@@ -86,24 +89,83 @@ Do this once in every Thread. (e.g. Rails -> ApplicationController)
 
 ```Ruby
 FastGettext.text_domain = 'my_app'
-FastGettext.available_locales = ['de','en','fr','en_US','en_UK'] # only allow these locales to be set (optional)
+FastGettext.available_locales = ['de', 'en', 'fr', 'en_US', 'en_UK'] # only allow these locales to be set (optional)
 FastGettext.locale = 'de'
 ```
 
 ### 4. Start translating
 
-```Ruby
-include FastGettext::Translation
-_('Car') == 'Auto'
-_('not-found') == 'not-found'
-s_('Namespace|not-found') == 'not-found'
-n_('Axis','Axis',3) == 'Achsen' #German plural of Axis
-_('Hello %{name}!') % {name: "Pete"} == 'Hello Pete!'
+FastGetText supports all the translation methods of [ruby-gettext](http://github.com/ruby-gettext/gettext) with added support for block defaults.
+(to get `*gettext` methods, use `FastGetText::TranslationAliased`)
+
+#### `_()` or `gettext()`: basic translation
+
+```ruby
+extend FastGettext::Translation
+_('Car') == 'Auto'             # found translation for 'Car'
+_('not-found') == 'not-found'  # The msgid is returned by default
+```
+
+#### `n_()` or `ngettext()`: pluralization
+
+```ruby
+n_('Car', 'Cars', 1) == 'Auto'
+n_('Car', 'Cars', 2) == 'Autos' # German plural of Cars
+```
+
+You'll often want to interpolate the results of `n_()` using ruby builtin `%` operator.
+
+```ruby
+n_('Car', '#{n} Cars', 2) % { n: count } == '2 Autos'
+```
+
+#### `p_()` or `pgettext()`: translation with context
+
+```ruby
+p_('File', 'Open') == _("File\004Open") == "öffnen"
+p_('Context', 'not-found') == 'not-found'
+```
+
+#### `s_()` or `sgetext()`: translation with namespace
+
+```ruby
+s_('File|Open') == _('File|Open') == "öffnen"
+s_('Context|not-found') == 'not-found'
+```
+
+The difference between `s_()` and `p_()` is largely based on how the translations
+are stored. Your preference will be based on your workflow and translation editing
+tools.
+
+#### `pn_()` or `pngettext()`: context-aware pluralized
+
+```ruby
+pn_('Fruit', 'Apple', 'Apples', 3) == 'Äpfel'
+pn_('Fruit', 'Apple', 'Apples', 1) == 'Apfel'
+```
+
+#### `sn_()` or `sngettext()`: without context pluralized
+
+```ruby
+sn_('Fruit|Apple', 'Apples', 3) == 'Äpfel'
+sn_('Fruit|Apple', 'Apples', 1) == 'Apfel'
+```
+
+#### `N_()` and `Nn_()`: make dynamic translations available to the parser.
+
+In many instances, your strings will not be found the by the ruby-parse. These methods
+allow for those strings to be discovered.
+
+```
+N_("active"); N_("inactive"); N_("paused") # possible value of status for parser to find.
+Nn_("active", "inactive", "paused")        # alternative method
+_("Your account is #{account_state}.") % { account_state: status }
 ```
 
 
 Managing translations
-============
+=====================
+
 ### mo/po-files
 Generate .po or .mo files using GetText parser (example tasks at [gettext_i18n_rails](http://github.com/grosser/gettext_i18n_rails))
 
@@ -113,12 +175,12 @@ Tell Gettext where your .mo or .po files lie, e.g. for locale/de/my_app.po and l
 FastGettext.add_text_domain('my_app', path: 'locale')
 ```
 
-Use the [original GetText](http://github.com/mutoh/gettext) to create and manage po/mo-files.
+Use the [original GetText](http://github.com/ruby-gettext/gettext) to create and manage po/mo-files.
 (Work on a po/mo parser & reader that is easier to use has started, contributions welcome @ [get_pomo](http://github.com/grosser/get_pomo) )
 
 ### Database
 [Example migration for ActiveRecord](http://github.com/grosser/fast_gettext/blob/master/examples/db/migration.rb)<br/>
-The default plural seperator is `||||` but you may overwrite it (or suggest a better one..).
+The default plural separator is `||||` but you may overwrite it (or suggest a better one..).
 
 This is usable with any model DataMapper/Sequel or any other(non-database) backend, the only thing you need to do is respond to the self.translation(key, locale) call.
 If you want to use your own models, have a look at the [default models](http://github.com/grosser/fast_gettext/tree/master/lib/fast_gettext/translation_repository/db_models) to see what you want/need to implement.
@@ -130,7 +192,7 @@ Rails
 Try the [gettext_i18n_rails plugin](http://github.com/grosser/gettext_i18n_rails), it simplifies the setup.<br/>
 Try the [translation_db_engine](http://github.com/grosser/translation_db_engine), to manage your translations in a db.
 
-Setting `available_locales`,`text_domain` or `locale` will not work inside the `evironment.rb`,
+Setting `available_locales`,`text_domain` or `locale` will not work inside the `environment.rb`,
 since it runs in a different thread then e.g. controllers, so set them inside your application_controller.
 
 ```Ruby
@@ -145,7 +207,7 @@ class ApplicationController ...
   include FastGettext::Translation
   before_filter :set_locale
   def set_locale
-    FastGettext.available_locales = ['de','en',...]
+    FastGettext.available_locales = ['de', 'en', ...]
     FastGettext.text_domain = 'frontend'
     FastGettext.set_locale(params[:locale] || session[:locale] || request.env['HTTP_ACCEPT_LANGUAGE'])
     session[:locale] = I18n.locale = FastGettext.locale
@@ -155,6 +217,7 @@ class ApplicationController ...
 
 Advanced features
 =================
+
 ### Abnormal pluralisation
 Plurals are selected by index, think of it as `['car', 'cars'][index]`<br/>
 A pluralisation rule decides which form to use e.g. in english its `count == 1 ? 0 : 1`.<br/>
@@ -163,7 +226,7 @@ If you have any languages that do not fit this rule, you have to add a custom pl
 Via Ruby:
 
 ```Ruby
-FastGettext.pluralisation_rule = lambda{|count| count > 5 ? 1 : (count > 2 ? 0 : 2)}
+FastGettext.pluralisation_rule = ->(count){ count > 5 ? 1 : (count > 2 ? 0 : 2)}
 ```
 
 Via mo/pofile:
@@ -179,7 +242,7 @@ If you only use one text domain, setting `FastGettext.default_text_domain = 'app
 is sufficient and no more `text_domain=` is needed
 
 ### default_locale
-If the simple rule of "first `availble_locale` or 'en'" is not suficcient for you, set `FastGettext.default_locale = 'de'`.
+If the simple rule of "first `available_locale` or 'en'" is not sufficient for you, set `FastGettext.default_locale = 'de'`.
 
 ### default_available_locales
 Fallback when no available_locales are set
@@ -203,7 +266,7 @@ repos = [
   FastGettext::TranslationRepository.build('new', path: '....'),
   FastGettext::TranslationRepository.build('old', path: '....')
 ]
-FastGettext.add_text_domain 'combined', type: :chain, :chain: repos
+FastGettext.add_text_domain 'combined', type: :chain, chain: repos
 ```
 
 ### Merge
@@ -213,8 +276,8 @@ a subordinate repository is added. This puts the burden on the load phase and sp
 
 ```Ruby
 repos = [
-  FastGettext::TranslationRepository.build('new', :path: '....'),
-  FastGettext::TranslationRepository.build('old', :path: '....')
+  FastGettext::TranslationRepository.build('new', path: '....'),
+  FastGettext::TranslationRepository.build('old', path: '....')
 ]
 domain = FastGettext.add_text_domain 'combined', type: :merge, chain: repos
 ```
@@ -232,7 +295,7 @@ When you want to know which keys could not be translated or were used, add a Log
 ```Ruby
 repos = [
   FastGettext::TranslationRepository.build('app', path: '....')
-  FastGettext::TranslationRepository.build('logger', type: :logger, callback: lambda{|key_or_array_of_ids| ... }),
+  FastGettext::TranslationRepository.build('logger', type: :logger, callback: ->(key_or_array_of_ids) { ... }),
 }
 FastGettext.add_text_domain 'combined', type: :chain, chain: repos
 ```
@@ -246,7 +309,7 @@ Want a xml version ?
 Write your own TranslationRepository!
 
 ```Ruby
-# fast_gettext/translation_repository/xxx.rb
+# fast_gettext/translation_repository/wtf.rb
 module FastGettext
   module TranslationRepository
     class Wtf
@@ -263,33 +326,65 @@ If you have more than one gettext domain, there are two sets of functions
 available:
 
 ```Ruby
-include FastGettext::TranslationMultidomain
+extend FastGettext::TranslationMultidomain
 
 d_("domainname", "string") # finds 'string' in domain domainname
 dn_("domainname", "string", "strings", 1) # ditto
-# etc.
+dp_("domainname", "context", "key")
+ds_("domainname", "context|key")
+dnp_("domainname", "context", "string", "strings")
+dns_("domainname", "context|string", "strings")
 ```
 
 These are helper methods so you don't need to write:
 
 ```Ruby
-FastGettext.text_domain = "domainname"
-_("string")
+FastGettext.with_domain("domainname") { _("string") }
 ```
 
 It is useful in Rails plugins in the views for example. The second set of
 functions are D functions which search for string in _all_ domains. If there
 are multiple translations in different domains, it returns them in random
-order (depends on the Ruby hash implementation):
+order (depends on the Ruby hash implementation).
 
 ```Ruby
-include FastGettext::TranslationMultidomain
+extend FastGettext::TranslationMultidomain
 
 D_("string") # finds 'string' in any domain
-# etc.
+Dn_("string", "strings", 1) # ditto
+Dp_("context", "key")
+Ds_("context|key")
+Dnp_("context", "string", "strings")
+Dns_("context|string", "strings")
+```
+
+Alternatively you can use [merge repository](https://github.com/grosser/fast_gettext#merge) to achieve the same behavior.
+
+#### Block defaults
+
+All the translation methods (includ MultiDomain) support a block default, a feature not provided by ruby-gettext.  When a translation is
+not found, if a block is provided the block is always returned. Otherwise, a key is returned. Methods doing pluralization will attempt a simple translation of alternate keys.
+
+```ruby
+_('not-found'){ "alternative default" } == alternate default
+```
+
+This block default is useful when the default is a very long passage of text that wouldn't make a useful key. You can also instrument logging not found keys.
+
+```ruby
+_('terms-and-conditions'){
+  load_terms_and_conditions
+  request_terms_and_conditions_translation_from_legal
+}
+
+# Override _ with logging
+def _(key, &block)
+  result = gettext(key){ nil } # nil returned when not found
+  log_missing_translation_key(key) if result.nil?
+  result || (block ? block.call : key)
+end
 ```
 
-Alternatively you can use [merge repository](https://github.com/grosser/fast_gettext#merge) to achieve the same behaviour.
 
 FAQ
 ===
@@ -297,13 +392,8 @@ FAQ
  - [Iconv require error in 1.9.2](http://exceptionz.wordpress.com/2010/02/03/how-to-fix-the-iconv-require-error-in-ruby-1-9)
 
 
-TODO
-====
- - Add a fallback for Iconv.conv in ruby 1.9.4 -> lib/fast_gettext/vendor/iconv
- - YML backend that reads ActiveSupport::I18n files
-
-Author
-======
+Authors
+=======
 Mo/Po-file parsing from Masao Mutoh, see vendor/README
 
 ### [Contributors](http://github.com/grosser/fast_gettext/contributors)
@@ -327,6 +417,7 @@ Mo/Po-file parsing from Masao Mutoh, see vendor/README
  - [Martin Meier](https://github.com/mameier)
  - [morcoteg](https://github.com/morcoteg)
  - [Daniel Schepers](https://github.com/tall-dan)
+ - [Robert Graff](https://github.com/rgraff)
 
 [Michael Grosser](http://grosser.it)<br/>
 michael@grosser.it<br/>

data/lib/fast_gettext.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fast_gettext/mo_file'
 require 'fast_gettext/storage'
 require 'fast_gettext/translation'
@@ -6,30 +8,28 @@ require 'fast_gettext/vendor/string'
 require 'fast_gettext/version'
 
 module FastGettext
-  include FastGettext::Storage
-  extend self
+  extend FastGettext::Storage
+  extend FastGettext::Translation
 
-  LOCALE_REX =  /^[a-z]{2,3}$|^[a-z]{2,3}_[A-Z]{2,3}$/
+  LOCALE_REX = /^[a-z]{2,3}$|^[a-z]{2,3}_[A-Z]{2,3}$/.freeze
   NAMESPACE_SEPARATOR = '|'
+  CONTEXT_SEPARATOR = "\004"
 
-  # users should not include FastGettext, since this would contaminate their namespace
-  # rather use
-  # FastGettext.locale = ..
-  # FastGettext.text_domain = ..
-  # and
-  # include FastGettext::Translation
-  FastGettext::Translation.public_instance_methods.each do |method|
-    define_method method do |*args|
-      Translation.send(method,*args)
-    end
+  # helper block for changing domains
+  def self.with_domain(domain)
+    old_domain = FastGettext.text_domain
+    FastGettext.text_domain = domain
+    yield
+  ensure
+    FastGettext.text_domain = old_domain
   end
 
-  def add_text_domain(name,options)
-    translation_repositories[name] = TranslationRepository.build(name,options)
+  def self.add_text_domain(name, options)
+    translation_repositories[name] = TranslationRepository.build(name, options)
   end
 
   # some repositories know where to store their locales
-  def locale_path
+  def self.locale_path
     translation_repositories[text_domain].instance_variable_get(:@options)[:path]
   end
 end

data/lib/fast_gettext/cache.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FastGettext
   class Cache
     def initialize
@@ -8,13 +10,13 @@ module FastGettext
     def fetch(key)
       translation = @current[key]
       if translation.nil? # uncached
-        @current[key] = yield || false # TODO get rid of this false hack and cache :missing
+        @current[key] = yield || false # TODO: get rid of this false hack and cache :missing
       else
         translation
       end
     end
 
-    # TODO only used for tests, maybe if-else around it ...
+    # TODO: only used for tests, maybe if-else around it ...
     def []=(key, value)
       @current[key] = value
     end