fast_gettext 1.6.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 902a77bc80c4d7a349d121874e157d902d8927a1
-  data.tar.gz: 57e2ab68b62cb0abaa8657332b381306df515aea
+SHA256:
+  metadata.gz: 91bc0d49ead2bfbfad8065858e52255dfcd9938cb547f0b20984bb12cc202380
+  data.tar.gz: 45c2e546d2041e36b82a4d82593d4b1c014d46da561996037a76d6e911ed2cdb
 SHA512:
-  metadata.gz: c584454d8a8802e63c02f1d28d7ae4168f1f78335f9c052a077926c5f4828c70ff906df6f0fffd7603965fca9964a5c5fc82df462fd293ed78ee0b5be09cf952
-  data.tar.gz: 71f4ec7049fdfa4c0b98ffe4344ca5d929529ff580001ea816210ba0329ebe1c11dab179962c2f9cabf683425bd03d304af7327033a41e6262cf8530a49e04f4
+  metadata.gz: 1120024578b173fb99e2bf879b22654723efede889a98d7d950c8201aef11261566f6c70a6247f8ce937fef9f7ec88fe1a6dc9a874331e6cc41fbed55cc651f2
+  data.tar.gz: 6cdbf2dcec813b6fb0c0da4b87af33c372a2f87ea177fdafd0203cf3f45f565a5fe64b4e41fe4fedcd4450ec1a7196d4c5a015df35470b4cfdb8b21e4037b137

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,13 +63,15 @@ 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)
 
 ```Ruby
+# A single locale can be segmented in multiple yaml files but they all should be
+# named with a `qq.yml` suffix, where `qq` is the locale name.
 FastGettext.add_text_domain('my_app', path: 'config/locales', type: :yaml)
 ```
 
@@ -75,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)
 ```
 
@@ -84,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 `sgettext()`: 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 by the ruby parsing. 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))
 
@@ -111,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.
@@ -128,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
@@ -143,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
@@ -153,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/>
@@ -161,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:
@@ -177,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
@@ -201,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
@@ -211,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
 ```
@@ -230,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
 ```
@@ -240,11 +305,11 @@ Unfound may not always mean missing, if you choose not to translate a word becau
 A lambda or anything that responds to `call` will do as callback. A good starting point may be `examples/missing_translations_logger.rb`.
 
 ### Plugins
-Want a xml version ?
+Want an 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
@@ -261,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 (including 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
 ===
@@ -295,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)
@@ -323,8 +415,11 @@ Mo/Po-file parsing from Masao Mutoh, see vendor/README
  - [Dominic Cleal](https://github.com/domcleal)
  - [Tomas Strachota](https://github.com/tstrachota)
  - [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/>
 License: MIT, some vendor parts under the same license terms as Ruby (see headers)<br/>
-[![Build Status](https://travis-ci.org/grosser/fast_gettext.png)](https://travis-ci.org/grosser/fast_gettext)
+[![CI](https://github.com/grosser/fast_gettext/actions/workflows/actions.yml/badge.svg)](https://github.com/grosser/fast_gettext/actions/workflows/actions.yml)

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

data/lib/fast_gettext/mo_file.rb

@@ -1,13 +1,17 @@
+# frozen_string_literal: true
+
 require 'fast_gettext/vendor/mofile'
 module FastGettext
   # Responsibility:
   #  - abstract mo files for Mo Repository
   class MoFile
-    PLURAL_SEPERATOR = "\000"
+    PLURAL_SEPARATOR = "\000"
+    CONTEXT_SEPARATOR = "\004"
 
     # file => path or FastGettext::GetText::MOFile
-    def initialize(file, options={})
+    def initialize(file, options = {})
       @filename = file
+      @data = nil
       load_data if options[:eager_load]
     end
 
@@ -15,17 +19,21 @@ module FastGettext
       data[key]
     end
 
-    #returns the plural forms or all singular translations that where found
+    # returns the plural forms or all singular translations that where found
     # Car, Cars => [Auto,Autos] or []
     def plural(*msgids)
-      split_plurals(self[msgids*PLURAL_SEPERATOR].to_s)
+      split_plurals(self[msgids * PLURAL_SEPARATOR].to_s)
     end
 
     def pluralisation_rule
-      #gettext uses 0 as default rule, which would turn off all pluralisation, very clever...
-      #additionally parsing fails when directly accessing po files, so this line was taken from gettext/mofile
-      (data['']||'').split("\n").each do |line|
-        return lambda{|n|eval($2)} if /^Plural-Forms:\s*nplurals\s*\=\s*(\d*);\s*plural\s*\=\s*([^;]*)\n?/ =~ line
+      # gettext uses 0 as default rule, which would turn off all pluralisation, very clever...
+      # additionally parsing fails when directly accessing po files, so this line was taken from gettext/mofile
+      (data[''] || '').split("\n").each do |line|
+        if /^Plural-Forms:\s*nplurals\s*\=\s*(\d*);\s*plural\s*\=\s*([^;]*)\n?/ =~ line
+          return ->(n) do # rubocop:disable Lint/UnusedBlockArgument
+            eval($2) # rubocop:disable Security/Eval
+          end
+        end
       end
       nil
     end
@@ -36,35 +44,37 @@ module FastGettext
     end
 
     def self.empty
-      MoFile.new(File.join(File.dirname(__FILE__),'vendor','empty.mo'))
+      MoFile.new(File.join(File.dirname(__FILE__), 'vendor', 'empty.mo'))
     end
 
     private
 
     def load_data
-      @data = if @filename.is_a? FastGettext::GetText::MOFile
-        @filename
-      else
-        FastGettext::GetText::MOFile.open(@filename, "UTF-8")
-      end
+      @data =
+        if @filename.is_a? FastGettext::GetText::MOFile
+          @filename
+        else
+          FastGettext::GetText::MOFile.open(@filename, "UTF-8")
+        end
       make_singular_and_plural_available
     end
 
-    #(if plural==singular, prefer singular)
+    # (if plural==singular, prefer singular)
     def make_singular_and_plural_available
       data = {}
-      @data.each do |key,translation|
-        next unless key.include? PLURAL_SEPERATOR
+      @data.each do |key, translation|
+        next unless key.include? PLURAL_SEPARATOR
+
         singular, plural = split_plurals(key)
         translation = split_plurals(translation)
         data[singular] ||= translation[0]
         data[plural] ||= translation[1]
       end
-      @data.merge!(data){|key,old,new| old}
+      @data.merge!(data) { |_key, old, _new| old }
     end
 
     def split_plurals(singular_plural)
-      singular_plural.split(PLURAL_SEPERATOR)
+      singular_plural.split(PLURAL_SEPARATOR)
     end
   end
 end