inline_translation 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1712a04eec4217093462a4e8ce98265646adf6d5
-  data.tar.gz: 03182eb9ece86002f1334fdd89c4cba98e4f760b
+  metadata.gz: 4c43a8db80105aeb7be961e297ca2f9a3aabe463
+  data.tar.gz: 59d7a9fe4cfcfd4e6aa5ab7a4a1083c381d7b6f3
 SHA512:
-  metadata.gz: 6d18f77ae8291f105db60da48524990b5566c7038bb92402a16d166e0618618dc97fcc054d41fceffe6de15dbfc26362354c1a9e0f31d973205b1f53e873180b
-  data.tar.gz: df2bcc2e4a0f4e8d399598d9ce316d31ecab1ab519a14a0a7dd7c9ac36a3c231b6816c6d8d0b8584a886505fc7a7398b8b776d03a6ab4a04c95e7bcd2d665057
+  metadata.gz: 4c52ef16c8ccb78f6ebece9e129f89e25cb2bd904d52f36053f99d6dc69fbb235d1594600981f158afa8ecd5beffc67745e3814fe74ba73b64dc1ec8c3a5ff5d
+  data.tar.gz: 5e1905f57907db594ca8eb80e59da5e49dd2b3a730b06ed459d484a6bce5dbb200ec6108823fa9115fb2afcaba02af0c080fd9cd11322bd4a96fc10a54c62b14

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.gem

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in InlineTranslation.gemspec
+gemspec
+
+gem 'rails', '~> 4.1.0'
+gem 'bing_translator', '~> 4.4.0'
+
+group :development, :test do
+  gem 'byebug', require: nil
+  gem 'temping'
+  gem 'mocha'
+  gem 'sqlite3'
+  gem 'byebug'
+end
+
+group :test do
+  gem 'codeclimate-test-reporter', require: nil
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 James Kiesel
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# Inline Translation
+
+`inline_translation` is a gem which provides your application with a simple, easy-to-use way to perform inline translations of content, into a variety of languages.
+
+It's written as a wrapper for the fine [bing_translator gem](https://github.com/relrod/bing_translator-gem), but can be easily extended to using other translation services.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'inline_translation'
+```
+
+And then execute:
+
+    $ bundle
+
+Then, execute the install generator
+
+    $ rails g inline_translation:install
+
+And migrate
+
+    $ rake db:migrate
+
+Now you're all set up!
+
+## Usage
+
+Inline Translation supplies several helper methods to make your translating life easier.
+
+To mark a field on an object as translatable, simply add
+
+`acts_as_translatable, on: :field_name`
+
+to your model.
+
+#### Additional options
+
+- **load_via** - the class method used to find a record for your model. Defaults to `:find`
+- **id_field** - field name for the unique identifier for your model. Defaults to `:id`
+- **language_field** - field name for the method / column name on your model to retrieve the language. Defaults to `language`
+
+NB: Oftentimes, you may wish to delegate this method to a user or other object, instead of storing the language on every model.
+
+For example:
+
+```ruby
+# model.rb
+class Model < ActiveRecord::Base
+  belongs_to :author, class_name: 'User'
+  acts_as_translatable on: :column
+
+  def language
+    author.locale
+  end
+end
+```
+
+## On the frontend
+
+#### The translation link
+
+InlineTranslation provides a simple helper method for translation links in the view.
+
+For example, adding
+
+```ruby
+translate_link_for(@model, to: :fr)
+```
+
+Will add an ajax link to create and store a French translation. The `to` field will default to I18n.locale.
+
+###### Additional options
+
+- **text** - The text of the anchor generated. Defaults to 'Translate'
+- **to** - The language to translate to with this link. Defaults to I18n.locale
+
+(NB: This link will not appear if `@model.language` is equal to the 'to' parameter, since we cannot perform translations to the same language.)
+
+#### Populating the translation (via UJS)
+
+The simplest possible markup for including translations on callback:
+
+```ruby
+# /app/views/models/show.html.erb
+<div id="model-1">
+  <%= translated_element_for @model, :field_a %>
+  <%= translated_element_for @model, :field_b %>
+</div>
+```
+
+(Note that this markup can occur anywhere, as long as the `translated_element_for` elements are within a div of the format 'className-id')
+
+If this particular markup structure doesn't work for you for whatever reason, feel free to edit the `app/views/translations/create.js.erb` with javascript to your liking.
+
+###### Additional options
+
+- **element** - The type of element generated. Defaults to 'span'
+
+#### Populating the translation (via JSON)
+
+The `translations#create` action can also accept a `:json` format, which will return a list of serialized translations. These can be consumed by your javascript frontend framework as you see fit.
+(TODO: provide more robust support for custom serialization, such as through ActiveModel::Serializers PRs welcome!)
+
+ie, a simplistic implementation in angular:
+
+```html
+<!--in the view -->
+<a href='' ng-click='translateToFrench()'>Translate</a>
+```
+
+```javascript
+// in the controller
+$scope.translateToFrench = function() {
+  $http.post('/translations', { translatable_id: 1, translatable_type: 'Model', to: 'fr', format: 'json'}).then(function(data) {
+    $scope.frenchTranslation = data
+  })
+}
+```
+
+
+## On the backend
+
+InlineTranslation uses the Bing Translator API as a default. For instructions on setting up the Bing Translator API, [go here](https://github.com/relrod/bing_translator-gem#getting-a-client-id-and-secret).
+
+## Different Translators
+
+Simply change the line in `config/initializers/inline_translation.rb` to use whatever translator you desire.
+
+Note that a custom translator must implement the following methods:
+
+- `self.ready?`: Returns true if the translator can translate anything
+- `can_translate?`: Returns true the translator can translate the given translatable
+- `translate`: Returns a translation for all `acts_as_translatable` fields on the translatable
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/inline_translation/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+task default: :test
+
+Rake::TestTask.new :test do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+  t.warning = false
+end

data/app/controllers/translations_controller.rb

@@ -0,0 +1,42 @@
+module InlineTranslation
+  module Controllers
+    class TranslationsController < ::ApplicationController
+      respond_to :js, :json
+
+      def create
+        if service.translate(translatable, to: to_language)
+          @translations = translatable.translations.where(language: to_language)
+          respond_to do |format|
+            format.js { render :create }
+            format.json { render json: @translations } # TODO: support for AMS / custom serialization
+          end
+        else
+          failure_response
+        end
+      end
+
+      private
+
+      def failure_response
+        head :unprocessable_entity
+      end
+
+      def self.controller_path
+        :translations
+      end
+
+      def service
+        @service ||= InlineTranslation::Services::TranslationService.new
+      end
+
+      def translatable
+        @translatable ||= params[:translatable_type].classify.constantize.get_instance params[:translatable_id] rescue nil
+      end
+
+      def to_language
+        params[:to] || I18n.locale
+      end
+
+    end
+  end
+end

data/config/initializers/babbel.rb

@@ -0,0 +1,2 @@
+ActiveSupport.on_load(:active_record) { include InlineTranslation::Concerns::ActsAsTranslatable }
+ActiveSupport.on_load(:action_view)   { include InlineTranslation::Helpers::TranslationsHelper }

data/config/routes.rb

@@ -0,0 +1,3 @@
+Rails.application.routes.draw do
+  resources :translations, only: :create, module: 'inline_translation/controllers', as: :translations
+end

data/inline_translation.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'inline_translation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "inline_translation"
+  spec.version       = InlineTranslation::VERSION
+  spec.authors       = ["James Kiesel (gdpelican)"]
+  spec.email         = ["james@loomio.org"]
+
+  spec.summary       = "Store on-the-fly translations using Bing (or others!)"
+  spec.description   = "Sets up a framework for allowing inline translation of database content"
+  spec.homepage      = "http://www.github.com/gdpelican/inline_translation"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["app", "lib"]
+
+  spec.add_runtime_dependency "rails", "~> 4.1"
+  spec.add_runtime_dependency "bing_translator", "~> 4.4"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.7"
+end

data/lib/generators/inline_translation/install/install_generator.rb

@@ -0,0 +1,24 @@
+module InlineTranslation
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    desc "Adds InlineTranslation translations table & initializer"
+    source_root File.expand_path '../templates', __FILE__
+
+    def copy_migration
+      migration_template "add_inline_translations.rb", "db/migrate/add_inline_translations.rb"
+    end
+
+    def copy_initializer
+      copy_file "inline_translation.rb", "config/initializers/inline_translation.rb"
+    end
+
+    def copy_js_view
+      copy_file "create.js.erb", "app/views/translations/create.js.erb"
+    end
+
+    def self.next_migration_number(path)
+      @previous_migration_nr ||= Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+      @previous_migration_nr += 1
+    end
+  end
+end

data/lib/generators/inline_translation/install/templates/add_inline_translations.rb

@@ -0,0 +1,16 @@
+class AddInlineTranslations < ActiveRecord::Migration
+  def self.up
+    create_table :translations do |t|
+      t.integer :translatable_id
+      t.string  :translatable_type
+      t.string  :field
+      t.string  :language
+      t.text    :translation
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :translations
+  end
+end

data/lib/generators/inline_translation/install/templates/create.js.erb

@@ -0,0 +1,4 @@
+target = $('#<%= @translatable.class.to_s.downcase %>-<%= @translatable.id %>')
+<% @translations.each do |translation| %>
+  target.find('.inline-translation-translated.<%= translation.field %>-translated').html("<%= j translation.translation %>")
+<% end %>

data/lib/generators/inline_translation/install/templates/inline_translation.rb

@@ -0,0 +1 @@
+InlineTranslation.translator = InlineTranslation::Translators::Bing

data/lib/inline_translation.rb

@@ -0,0 +1,42 @@
+require 'active_support'
+require 'inline_translation/engine'
+
+module InlineTranslation
+  extend ActiveSupport::Autoload
+
+  cattr_accessor :translator
+
+  module Concerns
+    autoload :ActsAsTranslatable, 'inline_translation/concerns/acts_as_translatable'
+    autoload :Translatable,       'inline_translation/concerns/translatable'
+  end
+
+  module Controllers
+    autoload :TranslationsController, 'controllers/translations_controller'
+  end
+
+  module Generators
+    autoload :InstallGenerator,   'generators/install/install_generator'
+  end
+
+  module Helpers
+    autoload :TranslationsHelper, 'inline_translation/helpers/translations_helper'
+  end
+
+  module Models
+    autoload :Translation,        'inline_translation/models/translation'
+  end
+
+  module Services
+    autoload :TranslationService, 'inline_translation/services/translation_service'
+  end
+
+  module Translators
+    autoload :Base,               'inline_translation/translators/base'
+    autoload :Bing,               'inline_translation/translators/bing'
+    autoload :Null,               'inline_translation/translators/null'
+  end
+
+  self.translator ||= Translators::Null
+
+end

data/lib/inline_translation/concerns/acts_as_translatable.rb

@@ -0,0 +1,17 @@
+module InlineTranslation
+  module Concerns
+    module ActsAsTranslatable
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def acts_as_translatable(on: [], load_via: :find, id_field: :id, language_field: :language)
+          include InlineTranslation::Concerns::Translatable
+          define_singleton_method :translatable_fields, -> { Array on }
+          define_singleton_method :get_instance,        ->(id) { send load_via, id }
+          define_method :id_field,                      -> { send id_field }
+          define_method :language_field,                -> { send language_field }
+        end
+      end
+    end
+  end
+end

data/lib/inline_translation/concerns/translatable.rb

@@ -0,0 +1,17 @@
+module InlineTranslation
+  module Concerns
+    module Translatable
+      extend ActiveSupport::Concern
+      included do
+        has_many :translations, as: :translatable, class_name: 'InlineTranslation::Models::Translation'
+        before_update :destroy_modified_translations
+
+        private
+
+        def destroy_modified_translations
+          translations.each { |t| t.destroy if changed.include? t.field }
+        end
+      end
+    end
+  end
+end