i18n-active_record 0.2.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6b1b7eba888729976d370e18c88c1710d818e8d4
-  data.tar.gz: cc0b86a33d8742fc2cf6a2db0bf3891681bc7b1c
+SHA256:
+  metadata.gz: a6895e3f4b2c615221ac6a44bba495f6a6557e76fe5815fe604005e3e9d455d0
+  data.tar.gz: febd2054212ebeec7624de340aebc0c9f86ae4ec509f55751f97459adef82bf9
 SHA512:
-  metadata.gz: 532cadaf5a7b6a349a4d84f5658be0c914521ec931e1c03089bd02d4e217279f080924568c8461c140ba3dd3d265eb5b3a017f817ec1723b91b6c6c4ca20aabd
-  data.tar.gz: c74ac31d2b20876ba61042b46de889f49f678f9fa23cf5d4173db7fc0d8ec4a878f779f03e53c76f563a051f99b2774fbcd7d28f3a7d9fe644cbf37b3880c184
+  metadata.gz: 3fbd83d43d6158a23eb0573a598c87c23986912403496761d60b9e72950d06ff0897e6e911bb2f3d1073ab0066e17d7aa02c0f288e6b2f43bacad3f306f31625
+  data.tar.gz: b51858da9da92d578fe190a185e45df9779e34dfb07c5b8daf097059edf18394c83fbbb1f2add6ac72b59e8ff19342f1ba3190bb72bee322a4430e25decce5ae

data/README.md

@@ -0,0 +1,165 @@
+# I18n::Backend::ActiveRecord [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop) [![Tests Status](https://github.com/svenfuchs/i18n-active_record/actions/workflows/test.yml/badge.svg)](https://github.com/svenfuchs/i18n-active_record/actions) [![Linter Status](https://github.com/svenfuchs/i18n-active_record/actions/workflows/linter.yml/badge.svg)](https://github.com/svenfuchs/i18n-active_record/actions)
+
+This repository contains the I18n ActiveRecord backend and support code that has been extracted from the `I18n` gem: http://github.com/svenfuchs/i18n.
+It is fully compatible with Rails 4+.
+
+## Installation
+
+For Bundler put the following in your Gemfile:
+
+```ruby
+gem 'i18n-active_record', require: 'i18n/active_record'
+```
+
+After updating your bundle, run the installer
+
+    $ rails g i18n:active_record:install
+
+It creates a migration:
+
+```ruby
+class CreateTranslations < ActiveRecord::Migration
+  def change
+    create_table :translations do |t|
+      t.string :locale
+      t.string :key
+      t.text :value
+      t.text :interpolations
+      t.boolean :is_proc, default: false
+
+      t.timestamps
+    end
+  end
+end
+```
+
+To specify table name use:
+
+    $ rails g i18n:active_record:install MyTranslation
+
+With the translation model you will be able to manage your translation, and add new translations or languages through
+it.
+
+By default the installer creates a new file in `config/initializers` named `i18n_active_record.rb` with the following content.
+
+```ruby
+require 'i18n/backend/active_record'
+
+Translation = I18n::Backend::ActiveRecord::Translation
+
+if Translation.table_exists?
+  I18n.backend = I18n::Backend::ActiveRecord.new
+
+  I18n::Backend::ActiveRecord.send(:include, I18n::Backend::Memoize)
+  I18n::Backend::Simple.send(:include, I18n::Backend::Memoize)
+  I18n::Backend::Simple.send(:include, I18n::Backend::Pluralization)
+
+  I18n.backend = I18n::Backend::Chain.new(I18n::Backend::Simple.new, I18n.backend)
+end
+```
+
+To perform a simpler installation use:
+
+    $ rails g i18n:active_record:install --simple
+
+It generates:
+
+```ruby
+require 'i18n/backend/active_record'
+I18n.backend = I18n::Backend::ActiveRecord.new
+```
+
+You may also configure whether the ActiveRecord backend should use `destroy` or `delete` when cleaning up internally.
+
+```ruby
+I18n::Backend::ActiveRecord.configure do |config|
+  config.cleanup_with_destroy = true # defaults to false
+end
+```
+
+To configure the ActiveRecord backend to cache translations(might be useful in production) use:
+
+```ruby
+I18n::Backend::ActiveRecord.configure do |config|
+  config.cache_translations = true # defaults to false
+end
+```
+
+The ActiveRecord backend can be configured to use a `scope` to isolate sets of translations. That way, two applications
+using the backend with the same database table can use translation data independently of one another.
+If configured with a scope, all data used will be limited to records with that particular scope identifier:
+
+```ruby
+I18n::Backend::ActiveRecord.configure do |config|
+  config.scope = 'app1' # defaults to nil, disabling scope
+end
+```
+
+## Usage
+
+You can now use `I18n.t('Your String')` to lookup translations in the database.
+
+## Custom translation model
+
+By default, the gem relies on [the built-in translation model](https://github.com/svenfuchs/i18n-active_record/blob/master/lib/i18n/backend/active_record/translation.rb).  
+However, to extend the default functionality, the translation model can be customized:
+
+```ruby
+class MyTranslation < I18n::Backend::ActiveRecord::Translation
+  def value=(val)
+    super("custom #{val}")
+  end
+end
+
+I18n::Backend::ActiveRecord.configure do |config|
+  config.translation_model = MyTranslation
+end
+```
+
+## Missing Translations
+
+To make the `I18n::Backend::ActiveRecord::Missing` module working correctly pluralization rules should be configured properly.
+The `i18n.plural.keys` translation key should be present in any of the backends.
+See https://github.com/svenfuchs/i18n-active_record/blob/master/lib/i18n/backend/active_record/missing.rb for more information.
+
+```yaml
+en:
+  i18n:
+    plural:
+      keys:
+        - :zero
+        - :one
+        - :other
+```
+
+### Interpolations
+
+The `interpolations` field in the `translations` table is used by `I18n::Backend::ActiveRecord::Missing` to store the interpolations seen the first time this Translation was requested.  This will help translators understand what interpolations to expect, and thus to include when providing the translations.
+
+The `interpolations` field is otherwise unused since the "value" in `Translation#value` is actually used for interpolation during actual translations.
+
+## Examples
+
+* http://collectiveidea.com/blog/archives/2016/05/31/beyond-yml-files-dynamic-translations/ ([use `before_action`](https://github.com/svenfuchs/i18n-active_record/issues/138) for Rails 5.1+)
+
+## Contributing
+
+### Test suite
+
+The test suite can be run with:
+
+    bundle exec rake
+
+By default it runs the tests for SQLite database, to specify a database the `DB` env variable can be used:
+
+    DB=postgres bundle exec rake
+    DB=mysql bundle exec rake
+
+To run tests for a specific rails version see [Appraisal](https://github.com/thoughtbot/appraisal):
+
+    bundle exec appraisal rails-4 rake test
+
+## Maintainers
+
+* Sven Fuchs
+* Tim Masliuchenko

data/Rakefile

@@ -1,61 +1,12 @@
-require 'rake'
+# frozen_string_literal: true
+
 require 'rake/testtask'
 require 'bundler/gem_tasks'
 
-def execute(command)
-  puts command
-  system command
-end
-
-def bundle_options
-  opt = ''
-  opt +=  "--gemfile #{ENV['BUNDLE_GEMFILE']}" if ENV['BUNDLE_GEMFILE']
-end
-
-def each_database(&block)
-  ['sqlite', 'postgres', 'mysql'].each &block
-end
-
-namespace :bundle do
-  task :env do
-    ar = ENV['AR'].to_s
-
-    next if ar.empty?
-
-    gemfile = "gemfiles/Gemfile.rails_#{ar}"
-    raise "Cannot find gemfile at #{gemfile}" unless File.exist?(gemfile)
-
-    ENV['BUNDLE_GEMFILE'] = gemfile
-    puts "Using gemfile: #{gemfile}"
-  end
-
-  task install: :env do
-    execute "bundle install #{bundle_options}"
-  end
-
-  task :install_all do
-    [nil, '3', '4', '5', 'master'].each do |ar|
-      opt = ar && "AR=#{ar}"
-      execute "rake bundle:install #{opt}"
-    end
-  end
-end
-
-task :test do
-  each_database { |db| execute "rake #{db}:test" }
-end
-
-Rake::TestTask.new :_test do |t|
+Rake::TestTask.new :test do |t|
   t.libs << 'test'
   t.pattern = 'test/**/*_test.rb'
   t.verbose = false
 end
 
-each_database do |db|
-  namespace db do
-    task(:env) { ENV['DB'] = db }
-    task test: ['env', 'bundle:env', '_test']
-  end
-end
-
 task default: :test

data/lib/generators/i18n/active_record/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_record'
+
+module I18n
+  module ActiveRecord
+    module Generators
+      class  InstallGenerator < ::ActiveRecord::Generators::Base
+        desc 'Installs i18n-active_record and generates the necessary migrations'
+
+        argument :name, type: :string, default: 'Translation'
+
+        class_option :simple, type: :boolean, default: false, desc: 'Perform the simple setup'
+
+        source_root File.expand_path('templates', __dir__)
+
+        def copy_initializer
+          tpl = "#{options[:simple] ? 'simple' : 'advanced'}_initializer.rb.erb"
+
+          template tpl, 'config/initializers/i18n_active_record.rb'
+        end
+
+        def create_migrations
+          migration_template 'migration.rb.erb', "db/migrate/create_#{table_name}.rb"
+        end
+      end
+    end
+  end
+end

data/lib/generators/i18n/active_record/templates/advanced_initializer.rb.erb

@@ -0,0 +1,19 @@
+require 'i18n/backend/active_record'
+
+Translation = I18n::Backend::ActiveRecord::Translation
+
+if Translation.table_exists?
+  I18n.backend = I18n::Backend::ActiveRecord.new
+
+  I18n::Backend::ActiveRecord.send(:include, I18n::Backend::Memoize)
+  I18n::Backend::Simple.send(:include, I18n::Backend::Memoize)
+  I18n::Backend::Simple.send(:include, I18n::Backend::Pluralization)
+
+  I18n.backend = I18n::Backend::Chain.new(I18n::Backend::Simple.new, I18n.backend)
+end
+
+I18n::Backend::ActiveRecord.configure do |config|
+  # config.cache_translations = true # defaults to false
+  # config.cleanup_with_destroy = true # defaults to false
+  # config.scope = 'app_scope' # defaults to nil, won't be used
+end

data/lib/generators/i18n/active_record/templates/migration.rb.erb

@@ -0,0 +1,14 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string :scope
+      t.string :locale
+      t.string :key
+      t.text :value
+      t.text :interpolations
+      t.boolean :is_proc, default: false
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/i18n/active_record/templates/simple_initializer.rb.erb

@@ -0,0 +1,8 @@
+require 'i18n/backend/active_record'
+I18n.backend = I18n::Backend::ActiveRecord.new
+
+I18n::Backend::ActiveRecord.configure do |config|
+  # config.cache_translations = true # defaults to false
+  # config.cleanup_with_destroy = true # defaults to false
+  # config.scope = 'app_scope' # defaults to nil, won't be used
+end

data/lib/i18n/active_record/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module I18n
   module ActiveRecord
-    VERSION = '0.2.2'
+    VERSION = '1.4.0'
   end
 end

data/lib/i18n/active_record.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'i18n'

data/lib/i18n/backend/active_record/configuration.rb

@@ -1,11 +1,16 @@
+# frozen_string_literal: true
+
 module I18n
   module Backend
     class ActiveRecord
       class Configuration
-        attr_accessor :cleanup_with_destroy
+        attr_accessor :cleanup_with_destroy, :cache_translations, :translation_model, :scope
 
         def initialize
           @cleanup_with_destroy = false
+          @cache_translations = false
+          @translation_model = I18n::Backend::ActiveRecord::Translation
+          @scope = nil
         end
       end
     end

data/lib/i18n/backend/active_record/missing.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #  This extension stores translation stub records for missing translations to
 #  the database.
 #
@@ -34,29 +36,31 @@ module I18n
     class ActiveRecord
       module Missing
         include Flatten
+        include TranslationModel
 
         def store_default_translations(locale, key, options = {})
-          count, scope, default, separator = options.values_at(:count, :scope, :default, :separator)
+          count, scope, _, separator = options.values_at(:count, :scope, :default, :separator)
           separator ||= I18n.default_separator
           key = normalize_flat_keys(locale, key, scope, separator)
 
-          unless ActiveRecord::Translation.locale(locale).lookup(key).exists?
-            interpolations = options.keys - I18n::RESERVED_KEYS
-            keys = count ? I18n.t('i18n.plural.keys', :locale => locale).map { |k| [key, k].join(FLATTEN_SEPARATOR) } : [key]
-            keys.each { |key| store_default_translation(locale, key, interpolations) }
-          end
+          return if translation_model.locale(locale).lookup(key).exists?
+
+          interpolations = options.keys - I18n::RESERVED_KEYS
+          keys = count ? I18n.t('i18n.plural.keys', locale: locale).map { |k| [key, k].join(FLATTEN_SEPARATOR) } : [key]
+          keys.each { |k| store_default_translation(locale, k, interpolations) }
         end
 
         def store_default_translation(locale, key, interpolations)
-          translation = ActiveRecord::Translation.new :locale => locale.to_s, :key => key
+          translation = translation_model.new locale: locale.to_s, key: key
           translation.interpolations = interpolations
           translation.save
         end
 
         def translate(locale, key, options = {})
           result = catch(:exception) { super }
+
           if result.is_a?(I18n::MissingTranslation)
-            self.store_default_translations(locale, key, options)
+            store_default_translations(locale, key, options)
             throw(:exception, result)
           else
             result

data/lib/i18n/backend/active_record/store_procs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This module is intended to be mixed into the ActiveRecord backend to allow
 # storing Ruby Procs as translation values in the database.
 #
@@ -21,19 +23,20 @@ module I18n
   module Backend
     class ActiveRecord
       module StoreProcs
-        def value=(v)
-          case v
+        extend TranslationModel
+
+        def value=(val)
+          case val
           when Proc
-            write_attribute(:value, v.to_ruby)
+            write_attribute(:value, val.to_ruby)
             write_attribute(:is_proc, true)
           else
-            write_attribute(:value, v)
+            write_attribute(:value, val)
           end
         end
 
-        Translation.send(:include, self) if method(:to_s).respond_to?(:to_ruby)
+        translation_model.send(:include, self) if method(:to_s).respond_to?(:to_ruby)
       end
     end
   end
 end
-

data/lib/i18n/backend/active_record/translation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_record'
 
 module I18n
@@ -51,21 +53,39 @@ module I18n
 
         self.table_name = 'translations'
 
-        serialize :value
-        serialize :interpolations, Array
+        if ::ActiveRecord.version >= Gem::Version.new('7.1.0.alpha')
+          serialize :value, coder: YAML
+          serialize :interpolations, coder: YAML, type: Array
+        else
+          serialize :value
+          serialize :interpolations, Array
+        end
+
+        before_validation :set_scope
+        after_commit :invalidate_translations_cache
+
+        default_scope { scoped }
 
         class << self
           def locale(locale)
-            where(:locale => locale.to_s)
+            where(locale: locale.to_s)
+          end
+
+          def scoped
+            if (record_scope = ActiveRecord.config.scope)
+              where(scope: record_scope)
+            else
+              all
+            end
           end
 
           def lookup(keys, *separator)
             column_name = connection.quote_column_name('key')
-            keys = Array(keys).map! { |key| key.to_s }
+            keys = Array(keys).map!(&:to_s)
 
             unless separator.empty?
-              warn "[DEPRECATION] Giving a separator to Translation.lookup is deprecated. " <<
-                "You can change the internal separator by overwriting FLATTEN_SEPARATOR."
+              warn '[DEPRECATION] Giving a separator to Translation.lookup is deprecated. ' \
+                   'You can change the internal separator by overwriting FLATTEN_SEPARATOR.'
             end
 
             namespace = "#{keys.last}#{I18n::Backend::Flatten::FLATTEN_SEPARATOR}%"
@@ -73,12 +93,24 @@ module I18n
           end
 
           def available_locales
-            Translation.select('DISTINCT locale').to_a.map { |t| t.locale.to_sym }
+            select('DISTINCT locale').to_a.map { |t| t.locale.to_sym }
+          end
+
+          def to_h
+            all.each.with_object({}) do |t, memo|
+              locale_hash = (memo[t.locale.to_sym] ||= {})
+              keys = t.key.split('.')
+              keys.each.with_index.inject(locale_hash) do |iterator, (key_part, index)|
+                key = key_part.to_sym
+                iterator[key] = keys[index + 1] ? (iterator[key] || {}) : t.value
+                iterator[key] # rubocop:disable Lint/UnmodifiedReduceAccumulator
+              end
+            end
           end
         end
 
         def interpolates?(key)
-          self.interpolations.include?(key) if self.interpolations
+          interpolations&.include?(key)
         end
 
         def value
@@ -95,14 +127,25 @@ module I18n
         end
 
         def value=(value)
-          if value === false
+          case value
+          when false
             value = FALSY_CHAR
-          elsif value === true
+          when true
             value = TRUTHY_CHAR
           end
 
           write_attribute(:value, value)
         end
+
+        def invalidate_translations_cache
+          I18n.backend.reload! if I18n::Backend::ActiveRecord.config.cache_translations
+        end
+
+        private
+
+        def set_scope
+          self.scope ||= ActiveRecord.config.scope if ActiveRecord.config.scope
+        end
       end
     end
   end

data/lib/i18n/backend/active_record.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'i18n/backend/base'
 require 'i18n/backend/active_record/translation'
 
@@ -19,47 +21,83 @@ module I18n
         end
       end
 
+      def initialize
+        reload!
+      end
+
+      module TranslationModel
+        private
+
+        def translation_model
+          I18n::Backend::ActiveRecord.config.translation_model
+        end
+      end
+
       module Implementation
-        include Base, Flatten
+        include Base
+        include Flatten
+        include TranslationModel
 
         def available_locales
-          begin
-            Translation.available_locales
-          rescue ::ActiveRecord::StatementInvalid
-            []
-          end
+          translation_model.available_locales
+        rescue ::ActiveRecord::StatementInvalid
+          []
         end
 
         def store_translations(locale, data, options = {})
           escape = options.fetch(:escape, true)
+
           flatten_translations(locale, data, escape, false).each do |key, value|
-            translation = Translation.locale(locale).lookup(expand_keys(key))
+            translation = translation_model.locale(locale).lookup(expand_keys(key))
 
-            if ActiveRecord.config.cleanup_with_destroy
+            if self.class.config.cleanup_with_destroy
               translation.destroy_all
             else
               translation.delete_all
             end
 
-            Translation.create(:locale => locale.to_s, :key => key.to_s, :value => value)
+            translation_model.create(locale: locale.to_s, key: key.to_s, value: value)
           end
+
+          reload! if self.class.config.cache_translations
+        end
+
+        def reload!
+          @translations = nil
+
+          self
+        end
+
+        def initialized?
+          !@translations.nil?
+        end
+
+        def init_translations
+          @translations = translation_model.to_h
+        end
+
+        def translations(do_init: false)
+          init_translations if do_init || !initialized?
+          @translations ||= {}
         end
 
-      protected
+        protected
 
         def lookup(locale, key, scope = [], options = {})
           key = normalize_flat_keys(locale, key, scope, options[:separator])
-          if key.first == '.'
-            key = key[1..-1]
-          end
-          if key.last == '.'
-            key = key[0..-2]
+          key = key[1..-1] if key.first == '.'
+          key = key[0..-2] if key.last == '.'
+
+          if self.class.config.cache_translations
+            keys = ([locale] + key.split(I18n::Backend::Flatten::FLATTEN_SEPARATOR)).map(&:to_sym)
+
+            return translations.dig(*keys)
           end
 
           result = if key == ''
-            Translation.locale(locale).all
+            translation_model.locale(locale).all
           else
-            Translation.locale(locale).lookup(key)
+            translation_model.locale(locale).lookup(key)
           end
 
           if result.empty?
@@ -76,23 +114,25 @@ module I18n
 
         def build_translation_hash_by_key(lookup_key, translation)
           hash = {}
-          if lookup_key == ''
-            chop_range = 0..-1
+
+          chop_range = if lookup_key == ''
+            0..-1
           else
-            chop_range = (lookup_key.size + FLATTEN_SEPARATOR.size)..-1
+            (lookup_key.size + FLATTEN_SEPARATOR.size)..-1
           end
           translation_nested_keys = translation.key.slice(chop_range).split(FLATTEN_SEPARATOR)
           translation_nested_keys.each.with_index.inject(hash) do |iterator, (key, index)|
             iterator[key] = translation_nested_keys[index + 1] ?  {} : translation.value
             iterator[key]
           end
+
           hash
         end
 
         # For a key :'foo.bar.baz' return ['foo', 'foo.bar', 'foo.bar.baz']
         def expand_keys(key)
-          key.to_s.split(FLATTEN_SEPARATOR).inject([]) do |keys, key|
-            keys << [keys.last, key].compact.join(FLATTEN_SEPARATOR)
+          key.to_s.split(FLATTEN_SEPARATOR).inject([]) do |keys, k|
+            keys << [keys.last, k].compact.join(FLATTEN_SEPARATOR)
           end
         end
       end