voltron-translate 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1658719544a250f6aae2906d090e405a7614db52
-  data.tar.gz: 1a44aea7a63899dc077fa3871a6334e6e528aa3b
+  metadata.gz: 496b01a5fc6aef8382150266d811b2b0feddbd4e
+  data.tar.gz: 6db2b1e2291a17e376c74cee8744a674632c17d7
 SHA512:
-  metadata.gz: 6d48356fb02213c0d4d41e53cf2c6fc23c0bbba719a81252dadbc50e0acdcb89e8fe239d12f98d5bf77c2b44f3cf165c4ae1d6c640ef8334c4c78dc59f47f229
-  data.tar.gz: 5ceea071fb55ec9ccfc5b5fbda61d5c9c3966ff5fc0e95938c32c62085ce53cc31bb266eb6b99bdf50b742d347c3c35ad651ab9aeec1807f8ca074046c72ca4d
+  metadata.gz: eef4569dd7db4562ceed56dce7154fe081708b4f975b0b5b600a973bf68b30caf347cd8799a8a1253b87c22542ed69668da41e1501027ed9c04200b52313bd99
+  data.tar.gz: e27b55db4f9163ec69576d22a89845dff355f01a52d55dffa16705311cb5ed41d296924b8e878f7984cb8310e64901aedfd291d3542d769b25b187eec08130f4

data/README.md

@@ -26,6 +26,8 @@ Then run the following to create the voltron.rb initializer (if not exists alrea
 
 ## Usage
 
+### The Double Underscore Method
+
 Voltron Translate extends ActiveRecord::Base, ActionController::Base, ActionMailer::Base, and ActionView::Base with a __ (double underscore) method that makes internationalization and/or translating static phrases easier.
 
 Once installed, from any class that extends from any of the three rails classes you can use the double underscore method to allow for real time text translation. For example:
@@ -102,12 +104,103 @@ __("User with name %{person_name} has been saved successfully.", :de, person_nam
 
 Will always look for the above translation within de.csv
 
+### Backend Translations
+
+To add support for translations of dynamic text, i.e. - Text entered into a form, Voltron Translate adds a `translates` class method to models.
+
+```ruby
+class Company < ActiveRecord::Base
+
+  # translates :attribute_name1, :attribute_name2, :attribute_name3, ..., options={}
+  translates :name, :greeting, { locales: [:en, :es, :de, :"en-GB"], default: :en }
+
+end
+```
+
+Options to the `translates` method are optional, and, if any/all or omitted, the defaults are as follows:
+
+locales -> Defaults to Voltron.config.translates.locales, which itself defaults to Rails.application.config.i18n.available_locales
+default -> nil, will just return the value of the original attribute, i.e. - "name" or "greeting"
+
+The `translates` method adds locale specific version of the attribute(s) to the model with the following methods:
+
+`<attribute>_<locale>`
+
+`<attribute>_<locale>=`
+
+`<attribute>_<locale>?`
+
+`<attribute>_<locale>_will_change!`
+
+`<attribute>_<locale>_changed?`
+
+`<attribute>_<locale>_was`
+
+In addition, it will override the `<attribute>` method with one that takes a single, optional argument: the locale you want to return the text for. Consider the following:
+
+```ruby
+# Voltron.config.translate.locales = [:en, :es, :"en-GB"]
+class Company < ActiveRecord::Base
+
+  translates :name
+
+end
+```
+
+```ruby
+@company = Company.create(name: 'Company Name', name_es: 'Spanish Company Name', name_en_gb: 'British Company Name')
+
+@company.name # Returns 'Company Name'
+@company.name(:es) # Returns 'Spanish Company Name'
+@company.name(:invalid_locale) # Returns 'Company Name', since it ultimately will fall back to the original attribute
+
+# OR, access the locale directly:
+
+@company.name_es # Returns 'Spanish Company Name'
+@company.name_en_gb # Returns 'British Company Name'
+
+# Without specifying a specific locale in either the method call or +translates+ option, it will try and base it's lookup by the value of I18n.locale
+
+I18n.locale = :en
+@company.name # Returns 'Company Name'
+
+I18n.locale = :es
+@company.name # Returns 'Spanish Company Name', since our global locale is set to :es
+```
+
+Should go without saying, but to set the translation text on the frontend, you'd just create a separate form field for each locales text:
+
+```erb
+<%= form_for @company do |f| %>
+  
+  <div>
+    <%= f.label :name %>
+    <%= f.text_field :name %>
+  </div>
+
+  <div>
+    <%= f.label :name_es %>
+    <%= f.text_field :name_es %>
+  </div>
+
+  <div>
+    <%= f.label :name_en_gb %>
+    <%= f.text_field :name_en_gb %>
+  </div>
+
+<% end %>
+```
+
+Add the appropriate attributes to your strong params, so on, so on...
+
 ## Things to Note
 
 Setting `Voltron.config.translate.enabled` to `false` will never break any __() call, it simply causes it to ignore the locale argument (if specified) and return the interpolated string using the latter arguments (again, if any)
 
 Disabling translations simply disables any IO related actions that would occur normally, like building or looking up translations when __() methods are called.
 
+It also disables the locale specific text translation on any method call that was targeted with `translates`, meaning `@company.name(:es)` would be the equivalent of calling `@company.name`. Note that `@company.name_es` would still work as it normally would.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/app/models/voltron/translation.rb

@@ -0,0 +1,7 @@
+module Voltron
+  class Translation < ActiveRecord::Base
+
+    belongs_to :resource, polymorphic: true
+
+  end
+end

data/lib/generators/templates/db/migrate/create_voltron_translations.rb

@@ -0,0 +1,11 @@
+class CreateVoltronTranslations < ActiveRecord::Migration
+  def change
+    create_table :voltron_translations do |t|
+      t.integer :resource_id
+      t.string :resource_type
+      t.string :attribute_name
+      t.string :locale
+      t.text :translation
+    end
+  end
+end

data/lib/generators/voltron/translate/install_generator.rb

@@ -3,6 +3,8 @@ module Voltron
     module Generators
       class InstallGenerator < Rails::Generators::Base
 
+        source_root File.expand_path("../../../templates", __FILE__)
+
         desc 'Add Voltron Translate initializer'
 
         def inject_initializer
@@ -27,8 +29,11 @@ module Voltron
   # Whether or not translation is enabled
   # config.translate.enabled = true
 
-  # Which locales to build translation files for
-  # config.translate.locales << :en
+  # Which locales to build translation files for. This setting also
+  # determines the global default locales used with the `translates` class method
+  # For example, if this is [:en, :es, :de], calling `translates :attribute` in a model
+  # Will expose the methods `attribute_en`, `attribute_es`, and `attribute_de`
+  # config.translate.locales = Rails.application.config.i18n.available_locales
 
   # In what environments can translation generation occur. Recommended to keep this as development (default)
   # config.translate.build_environment << :development
@@ -36,6 +41,38 @@ CONTENT
             end
           end
         end
+
+        def copy_migrations
+          copy_migration 'create_voltron_translations'
+        end
+
+        protected
+
+          def copy_migration(filename)
+            if migration_exists?(Rails.root.join('db', 'migrate'), filename)
+              say_status('skipped', "Migration #{filename}.rb already exists")
+            else
+              copy_file "db/migrate/#{filename}.rb", Rails.root.join('db', 'migrate', "#{migration_number}_#{filename}.rb")
+            end
+          end
+
+          def migration_exists?(dirname, filename)
+            Dir.glob("#{dirname}/[0-9]*_*.rb").grep(/\d+_#{filename}.rb$/).first
+          end
+
+          def migration_id_exists?(dirname, id)
+            Dir.glob("#{dirname}/#{id}*").length > 0
+          end
+
+          def migration_number
+            @migration_number ||= Time.now.strftime('%Y%m%d%H%M%S').to_i
+
+            while migration_id_exists?(Rails.root.join('db', 'migrate'), @migration_number) do
+              @migration_number += 1
+            end
+
+            @migration_number
+          end
       end
     end
   end

data/lib/voltron/config/translate.rb

@@ -12,7 +12,7 @@ module Voltron
       def initialize
         @build_environment ||= [:development]
         @enabled ||= true
-        @locales ||= [:en]
+        @locales ||= I18n.available_locales
       end
 
       def enabled?
@@ -20,7 +20,7 @@ module Voltron
       end
 
       def buildable?
-        [build_environment].flatten.map(&:to_s).include?(Rails.env.to_s)
+        Array.wrap(build_environment).map(&:to_s).include?(Rails.env.to_s)
       end
     end
   end

data/lib/voltron/translatable.rb

@@ -0,0 +1,121 @@
+module Voltron
+  module Translatable
+
+    def translates(*attributes)
+      include InstanceMethods
+
+      options = (attributes.extract_options!).with_indifferent_access
+      locales = Array.wrap(options[:locales] || Voltron.config.translate.locales).map(&:to_s).map(&:underscore)
+
+      attributes.each do |attribute|
+
+        column = self.columns_hash[attribute.to_s]
+
+        raise ::ActiveRecord::UnknownAttributeError.new(self.new, attribute) if column.nil?
+
+        raise ::Voltron::Translate::InvalidColumnTypeError.new("Invalid type '#{column.type}' for attribute: #{attribute}. Translations only work on string and text attribute types.") unless [:string, :text].include?(column.type)
+
+        # Override the attribute with a method that accepts a specific locale as an argument
+        # If specified, will attempt to fetch that locale's translation, otherwise the default
+        # locale specified for the attribute, and ultimately the current locale translation
+        # If still nil, returns the value from super
+        define_method :"#{attribute}" do |locale=nil|
+          # +action_view/helpers/targs+ exist when this method is called from within
+          # ActionView::Helpers. In other words, form helper tags. In that
+          # case we want the actual value of the attribute, not whatever the locale is
+          return super() if caller.any? { |l| /action_view\/helpers\/tags/.match(l) } || !Voltron.config.translate.enabled?
+          try(:"#{attribute}_#{locale.to_s.underscore}") || try(:"#{attribute}_#{options[:default].to_s.underscore}") || try(:"#{attribute}_#{I18n.locale.to_s.underscore}") || super()
+        end
+
+        locales.each do |locale|
+
+          # Define setter, i.e. - +attribute_es=+
+          define_method :"#{attribute}_#{locale}=" do |val|
+            attribute_will_change! "#{attribute}_#{locale}"
+            instance_variable_set("@#{attribute}_#{locale}", val)
+          end
+
+          # Define getter, i.e - +attribute_es+
+          # If nil, calling this method will attempt to fetch the value
+          # We do this to avoid preloading the translations association records
+          define_method :"#{attribute}_#{locale}" do
+            if instance_variable_get("@#{attribute}_#{locale}").nil?
+              instance_variable_set("@#{attribute}_#{locale}", send(:"#{attribute}_#{locale}_was"))
+            end
+            instance_variable_get("@#{attribute}_#{locale}")
+          end
+
+          # Define the changed? method, i.e. - +attribute_es_changed?+
+          define_method :"#{attribute}_#{locale}_changed?" do
+            changed.include?("#{attribute}_#{locale}")
+          end
+
+          # Define the was method, i.e. - +attribute_es_was+
+          define_method :"#{attribute}_#{locale}_was" do
+            translations.find_by(attribute_name: attribute, locale: locale).try(:translation)
+          end
+
+          define_method :"#{attribute}_#{locale}_will_change!" do
+            attribute_will_change! "#{attribute}_#{locale}"
+          end
+
+          define_method :"#{attribute}_#{locale}?" do
+            instance_variable_get("@#{attribute}_#{locale}").present?
+          end
+
+        end
+      end
+
+      # In case +translates+ was called multiple times, merge in the new attributes/locales
+      # with the pre-existing ones
+      all_attributes = @_translations.try(:keys) || []
+      all_attributes += attributes
+      all_attributes.uniq!
+
+      all_locales = @_translations.try(:values) || []
+      all_locales += locales
+      all_locales.flatten!
+      all_locales.uniq!
+
+      has_many :translations, as: :resource, class_name: 'Voltron::Translation', dependent: :destroy
+
+      before_save :build_translations
+
+      accepts_nested_attributes_for :translations, reject_if: :all_blank, allow_destroy: true
+      
+      @_translations = all_attributes.map { |a| { a.to_s => all_locales } }.reduce(Hash.new, :merge)
+    end
+
+    module InstanceMethods
+
+      # Before validation, iterate over all possible translation methods
+      # and either update the corresponding translation record or build it,
+      # so it can be saved when the parent record is saved
+      def build_translations
+        self.translations_attributes = translation_methods.map do |m, t|
+          if send(:"#{m}_changed?")
+            # Find the translation if it previously existed, or create new one
+            translation = translations.where(attribute_name: t[:attribute], locale: t[:locale]).first || Voltron::Translation.new(attribute_name: t[:attribute], locale: t[:locale])
+            # Set the translation text on our returned translation object
+            translation.translation = instance_variable_get("@#{m}")
+            # Return the attributes of our translation that will be assigned to self.translations_attributes
+            translation.attributes
+          end
+        end.compact
+      end
+
+      private
+
+        def translate_translations
+          self.class.instance_variable_get('@_translations')
+        end
+
+        def translation_methods
+          translate_translations.map do |attribute, locales|
+            locales.map { |locale| { :"#{attribute}_#{locale}" => { attribute: attribute, locale: locale } } }
+          end.flatten.reduce(Hash.new, :merge)
+        end
+
+    end
+  end
+end

data/lib/voltron/translate/{railtie.rb → engine.rb}

@@ -1,12 +1,14 @@
-require 'voltron'
-
 module Voltron
   module Translate
-    class Railtie < Rails::Railtie
+    class Engine < Rails::Engine
+
+      isolate_namespace Voltron
+
       initializer 'voltron.translate.initialize' do
         ::ActionController::Base.send :include, ::Voltron::Translate
         ::ActiveRecord::Base.send :include, ::Voltron::Translate
         ::ActiveRecord::Base.send :extend, ::Voltron::Translate
+        ::ActiveRecord::Base.send :extend, ::Voltron::Translatable
         ::ActionView::Base.send :include, ::Voltron::Translate
         ::ActionMailer::Base.send :include, ::Voltron::Translate
       end

data/lib/voltron/translate/version.rb

@@ -1,5 +1,5 @@
 module Voltron
   module Translate
-    VERSION = '0.1.6'.freeze
+    VERSION = '0.2.0'.freeze
   end
 end

data/lib/voltron/translate.rb

@@ -1,6 +1,7 @@
 require 'voltron'
 require 'voltron/translate/version'
 require 'voltron/config/translate'
+require 'voltron/translatable'
 require 'digest'
 require 'csv'
 require 'google_hash'
@@ -8,6 +9,8 @@ require 'google_hash'
 module Voltron
   module Translate
 
+    class InvalidColumnTypeError < StandardError; end
+
     def __(text, locale = I18n.locale, **args)
       return (text % args) unless Voltron.config.translate.enabled?
 
@@ -143,4 +146,4 @@ module Voltron
   end
 end
 
-require 'voltron/translate/railtie' if defined?(Rails)
+require 'voltron/translate/engine' if defined?(Rails)

data/voltron-translate.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency 'rails', '>= 4.2'
-  spec.add_dependency 'voltron', '>= 0.2.0'
+  spec.add_dependency 'voltron', '~> 0.2.4'
   spec.add_dependency 'google_hash', '>= 0.9.0'
 
   spec.add_development_dependency 'bundler', '>= 1.12'
@@ -28,4 +28,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec-rails', '>= 3.4'
   spec.add_development_dependency 'sqlite3', '>= 1.2'
   spec.add_development_dependency 'simplecov', '0.11.0'
+  spec.add_development_dependency 'factory_girl_rails', '>= 4.7'
+  spec.add_development_dependency 'byebug'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: voltron-translate
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Eric Hainer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-07 00:00:00.000000000 Z
+date: 2017-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -28,16 +28,16 @@ dependencies:
   name: voltron
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.4
 - !ruby/object:Gem::Dependency
   name: google_hash
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +136,34 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.11.0
+- !ruby/object:Gem::Dependency
+  name: factory_girl_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - eric@commercekitchen.com
@@ -151,12 +179,15 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/models/voltron/translation.rb
 - bin/console
 - bin/setup
+- lib/generators/templates/db/migrate/create_voltron_translations.rb
 - lib/generators/voltron/translate/install_generator.rb
 - lib/voltron/config/translate.rb
+- lib/voltron/translatable.rb
 - lib/voltron/translate.rb
-- lib/voltron/translate/railtie.rb
+- lib/voltron/translate/engine.rb
 - lib/voltron/translate/version.rb
 - voltron-translate.gemspec
 homepage: https://github.com/ehainer/voltron-translate