active_translation 0.7.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1234e553819683f3b7d5f77a491a8a39e1c1aef7f5fdef19190e2f046c7debfd
+  data.tar.gz: 5823014a65f7a39d1f3cf625f30ab1021d8cc6def7b655aa2f8b893419f56a5a
+SHA512:
+  metadata.gz: b5c18a5c9df15dddbd68088de1e7ed409d354bd9097430f1294559606abb6b527311515bf59fef1b60fb912496cc5d952dc0e0cbe38c5fd453c7dbfd156183f9
+  data.tar.gz: 37384c54c3d287811635d616cafac796200ebc86c856ee5d827a9c2fd3c9db137abf7dfb7724250c3870a4718b590ebd58945b11a68f3b1ff4f138819756c1e8

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Sean Hogge
+
+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,365 @@
+# WARNING KLAXON WARNING
+
+🚨 ActiveTranslation is pre-1.0 🚨
+
+This means there may be unhandled edge cases and undiscovered bugs. Please don't use it in production without rigorous QA.
+
+If you find a bug or problem, please report it. If you have an idea for a new feature, please suggest it.
+
+
+# ActiveTranslation
+
+ActiveTranslation is a Rails plugin that lets you easily translate ActiveRecord models. With a single line added to that model, you can declare which columns, which locales, and what constraints to allow or prevent translation.
+
+ActiveTranslation was built at and is sponsored by [Talentronic](https://talentronic.com)
+
+
+## How does this differ from internationalization (`I18n`)?
+
+I18n is a great solution for elements of your app that are static, nearly static, aren't database-driven, or otherwise can be controlled or constrained in some fashion.
+
+It can't help you if you have something that's user-supplied. It can't help you if you need translations available without a deploy, on demand.
+
+Even in instances where it can help you, there are times when having hundreds of lines of YAML can become tedious or difficult to maintain.
+
+Consider something like product categories: you might allow product managers to create them as needed. If you want them translated, you now need to communicate this to someone who can update the translation files. It's not difficult or tedious at first.
+
+Instead, what if you just add a single line to your `Category` model. Now product managers can create new categories with whimsical abandon, and your international customers don't have to wait for engineering or a third party to copy/paste into a `.yml` file.
+
+
+## Installation
+
+Add the gem to your gemfile:
+
+```ruby
+gem "active_translation", git: "https://github.com/seanhogge/active_translation"
+```
+
+And then bundle:
+
+```bash
+bundle
+```
+
+Run the installer to add a migration and initializer:
+
+```ruby
+rails generate active_translation:install
+```
+
+Migrate your primary database:
+
+```ruby
+rails db:migrate
+```
+
+You will need to restart your rails server and your ActiveJob adapter process (if separate) if it was running when you installed and migrated.
+
+
+## Configuration
+
+The first step after installation is to configure your Google credentials. ActiveTranslation uses the Google Translate API in the background for translation. This is a bit more than just an API key.
+
+The general idea is:
+
+1. Create a project at https://console.cloud.google.com
+1. In “APIs & Services” > “Library” look for “Cloud Translation API”
+1. Create a Service Account and download the JSON key file
+1. Ensure billing is enabled, and all the other prerequisites that Google requires
+1. Extract the necessary data from that JSON file and plug those values into `config/initializers/active_translation.rb` by setting the appropriate environment variables
+
+Feel free to change the names of the environment variables, or to alter that initializer to assign those keys however you like. At Talentronic, we have an `APIConnection` model we use for stuff like that so we grab the credentials from there and assign them.
+
+You could also use something like `dotenv-rails` and create a `.env` file in your various environments.
+
+Or you could use the OS to define them, such as in an `/etc/environment` file.
+
+If you're using Kamal, you probably already have a way to manage secrets and add them to env variables - that works, too.
+
+Obvious reminder: whatever method you use, just make sure it's not committed to any repository, even once. If you do, make sure you get new credentials and expire/delete the credentials that got committed.
+
+That's the hard part!
+
+
+## Usage
+
+To any ActiveRecord model, add `translates` with a list of columns that should be translated, a list of locales and any constraints.
+
+Simplest form:
+
+```ruby
+translates :content, into: %i[es fr de]
+```
+
+### Into
+
+The `into` argument can be an array of locales, a symbol that matches a method that returns an array of locales, or a Proc that returns an array of locales.
+
+So you could do:
+
+```ruby
+translates :content, into: :method_that_returns_locales
+```
+
+or
+
+```ruby
+translates :content, into: -> { I18n.available_locales - [ I18n.default_locale ] }
+```
+
+> `it` is a recent Ruby syntactical grain of sugar. It's the same as `_1` which lets you skip the `{ |arg| arg == :stuff }` repetition
+
+#### Into All
+
+Because translating a model into all the locales your app may define is so common, you can pass `:all` to the `into` argument to achieve the same result as passing `-> { I18n.available_locales - [ I18n.default_locale ] }`.
+
+This means you cannot pass in your own method called "all" as a symbol, of course.
+
+### If Constraints
+
+An `if` constraint will prevent translating if it returns `false`.
+
+If you have a boolean column like `published`, you might do:
+
+```ruby
+translates :content, into: %i[es fr de], if: :published?
+```
+
+Or you can define your own method that returns a boolean:
+
+```ruby
+translates :content, into: %i[es fr de], if: :record_should_be_translated?
+```
+
+Or you can use a Proc:
+
+```ruby
+translates :content, into: %i[es fr de], if: -> { content.length > 10 }
+```
+
+### Unless Constraints
+
+These work exactly the same as the `if` constraint, but the logic is flipped. If the constraint returns `true` then no translating will take place.
+
+### Constraint Compliance
+
+If your record is updated such that either an `if` or `unless` constraint is toggled, this will trigger the addition _or removal_ of translation data. The idea here is that the constraint controls whether a translation should _exist_, not whether a translation should be performed.
+
+This means if you use a constraint that frequently changes value, you will be paying for half of all change events.
+
+This is intentional. Translations are regenerated any time one of the translated attributes changes. But what about something like a `Post` that shouldn't be translated until it's published? There's no sense in translating it dozens of times as it's edited, but clicking the “publish” button doesn't update the translatable attributes.
+
+So ActiveTranslation watches for the constraint to change so that when the `Post` is published, the translation is performed with no extra effort.
+
+Likewise, if the constraint changes the other way, translations are removed since ActiveTranslation will no longer be keeping those translations up-to-date. Better to have no translation than a completely wrong one.
+
+### Manual Attributes
+
+Sometimes you want to translate an attribute, but it's not something Google Translate or an LLM can handle on their own. For instance, at Talentronic, we have names of businesses that operate in airports. These names have trademarked names that might look like common words, but aren't. These names also have the airport included which can confuse the LLM or API when it's mixed in with the business name.
+
+So we need manual translation attributes:
+
+```ruby
+translates :content, manual: :name, into: %i[es fr]
+```
+
+Manual attributes have a special setter in the form of `#{locale}_#{attribute_name}`. So in this example, we get `fr_name=` and `es_name=`.
+
+These attributes never trigger retranslation, and are never checked against the original text - it's entirely up to you to maintain them. However, it does get stored alongside all the other translations, keeping your database tidy and your translation code consistent.
+
+### The Show
+
+Once you have added the `translates` directive with your columns, locales, and constraints and your models have been translated to at least one locale, it's time to actually use them.
+
+If you set:
+
+```ruby
+translates :content, manual: :name, into: %i[es fr]
+```
+
+on a `Post` model, then you can simply call `.content` and it will use the current locale from Rails `I18n`.
+
+If you need the value for a locale other than the current, you can specify the locale explicitly:
+
+```ruby
+@post.content(locale: :fr)
+```
+
+If the post has an `fr_translation`, then that will be shown. If no `fr_translation` exists, it will show the post's untranslated `content`.
+
+In this way, you'll never have missing values, but you will have the default language version instead of the translated version.
+
+The same goes for manual translations:
+
+```ruby
+@post.name
+```
+
+returns the translated name for the current locale if it exists, or the untranslated `name` if it does.
+
+```ruby
+@post.name(locale: :es)
+```
+
+Regardless of the current locale, it will return the `:es` translated value for the `name` attribute, or the untranslated `name` if the `es_translation` doesn't exist.
+
+
+### Extras
+
+There are a few niceties provided to make ActiveTranslation as flexible as possible.
+
+Ideal world: you won't need them.
+Real world: you might need them.
+
+#### Translate on Demand
+
+There may be times when things get hosed. You might need or want to translate the automatic columns manually. You can do this in three ways:
+
+##### translate_if_needed
+
+By calling `translate_if_needed`, you can run the same checks that would occur on update. This is similar to calling `touch`, but it doesn't update the `updated_at` timestamp
+
+This will schedule the translation as a background job
+
+##### translate!
+
+By calling `translate!`, you skip all checks for whether a translation is outdated or missing and generate a new translation even if it's already extant and accurate.
+
+This will schedule the translation as a background job.
+
+##### translate_now!(locales)
+
+By calling `translate_now!` and optionally passing 1 or more locales, you skip all checks for whether a translation is outdated or missing and generate a new translation for the passed locales even if they're already extant and accurate.
+
+The default value for locales is `translatable_locales`, so if you don't pass anything, it will translate into all locales defined for that model.
+
+This method does **not** schedule the job, and instead immediately performs the translation, blocking until the translations for all locales are complete.
+
+#### Introspection
+
+The goal of ActiveTranslation is to make translations as automatic and invisible as possible. However, there may be times when you need to know the state of translations on a model instance.
+
+##### translation_checksum
+
+By calling `translation_checksum`, you can return the checksum used on a record to determine whether translations are outdated.
+
+##### translations_outdated?
+
+By calling `translations_outdated?`, you can get `true` if any translation has a checksum that no longer matches the source (otherwise you get `false`).
+
+This has limited value, but is provided in case you need to handle situations in which models change without triggering callbacks.
+
+> NOTE: `translations_outdated?` will _always_ return `false` if the conditions you passed (`if` & `unless`) are not met
+
+##### outdated_translations
+
+By calling `outdated_translations`, you can get an array of all `translations` that are outdated.
+
+This has limited value, but is provided in case you need to handle situations in which models change without triggering callbacks.
+
+##### translations_missing?
+
+By calling `translations_missing?`, you can get `true` if any translations are missing. This is a complex question, and is `false` unless:
+
+- any automatic translation attributes are not blank
+- any automatic translation attributes are missing an entry for any locale (in addition to not being blank)
+
+So if you have `translates :title, manual: :name, into: :all` and your app supports `:fr` and `:es`, you will get `true` if:
+
+- the `title` has been translated into `:es`, but not `:fr`
+- no translations exist at all
+- the `name` has been translated into both `:es` and `:fr` but `title` hasn't been translated
+- the `name` has been translated into both `:es` and `:fr` but `title` has been translated into only one locale
+
+and you will get `false` if:
+
+- translations conditions are not met, regardless of the presence or absence of any translations
+- the `title` column is blank (`nil` or empty string)
+- the `title` column has been fully translated but the `name` column has not been (manual attributes are ignored)
+- the `title` column has been fully translated, but the `title` column has changed since the translation in a way that doesn't trigger callbacks
+
+This has limited value, but is provided in case you need to handle situations in which models change without triggering callbacks.
+
+##### fully_translated?(auto_or_manual_or_all)
+
+By calling `fully_translated?` with no arguments, you can get `true` if all attributes are translated. This ignores manual attributes by default.
+
+There are some special symbols you can pass to change the scope of "fully." If you pass `:all` or `:include_manual`, then you will get `true` only if all automatic _and_ manual attributes have a translation.
+
+If you pass `:manual` or `:manual_only`, then you will get `true` only if all manual attributes have a translation, disregarding automatic attributes.
+
+Passing `:auto` or `:auto_only` is the same as passing no argument.
+
+Passing an invalid argument raises an error.
+
+> NOTE: `fully_translated?` will _always_ return `true` if the conditions you passed (`if` & `unless`) are not met
+
+##### translatable_locales
+
+By calling `translatable_locales`, you will get an array of locales for which the object will be translated. This has no bearing on whether any translations exist, or any conditions for translations to be performed.
+
+> NOTES: This is only defined on instances of a model, not the model itself, since the `into` argument allows more than just an Array literal.
+
+##### translation_config
+
+You can call `translation_config` on a model or instance to see what you've set up for translations. You'll see something like:
+
+```ruby
+> Page.translation_config
+=> {attributes: [:title, :heading, :subhead, :content], manual_attributes: [], locales: :all, unless: nil, if: :published?}
+
+> Category.translation_config
+=> {attributes: [:name, :short_name],
+ manual_attributes: [],
+ locales: #<Proc:0x000000012231a2b8 /path/to/projects/active_translation/app/models/category.rb:67 (lambda)>,
+ unless: nil,
+ if: nil}
+
+> Widget.translation_config
+=> {attributes: [:title, :headline, :ad_html],
+ manual_attributes: [],
+ locales: [:es, :fr],
+ unless: #<Proc:0x00000001228fea58 /path/to/projects/active_translation/app/models/widget.rb:42 (lambda)>,
+ if: nil}
+
+> Widget.last.translation_config
+=> {attributes: [:title, :headline, :ad_html],
+ manual_attributes: [],
+ locales: [:es, :fr],
+ unless: #<Proc:0x00000001228fea58 /path/to/projects/active_translation/app/models/widget.rb:42 (lambda)>,
+ if: nil}
+
+> Account.translation_config
+=> {attributes: [:profile_html], manual_attributes: ["name"], locales: :method_that_returns_locales, unless: nil, if: nil}
+```
+
+#### Disclaimer
+
+ActiveTranslation doesn't check the accuracy of translations in any way. It assumes that the response from Google is always perfect. If you are translating sensitive content where accuracy is critical in a legal or existential sense, you must handle translation auditing separately.
+
+So if you use the for an EULA, make it a manual attribute or don't use ActiveTranslation for it at all.
+
+ActiveTranslation doesn't redact any content. It assumes you would never send PII or financial data for translation. So... please don't.
+
+## Testing
+
+Ideally, you do not need to write any tests for translations or how they behave, since ActiveTranslation tests itself.
+
+However, perhaps you bolt on additional functionality to tests, or translations are critical to your application, or you simply want to ensure you're expecting the correct results from using the gem. In that case, ActiveTranslation provides some simple testing features.
+
+All translations skip the call to Google in the test environment, and return a simple modification of that content. For example, translating into the `:fr` locale in a test environment would behave as so:
+
+- Input: "auto translated content from ActiveRecord object"
+- Output: "[fr] auto translated content from ActiveRecord object"
+
+
+## Contributing
+
+Fork the repo, make your changes, make a pull request.
+
+Or simply report issues on the [GitHub repository](https://github.com/seanhogge/active_translation)
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/active_translation/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/active_translation/application_controller.rb

@@ -0,0 +1,4 @@
+module ActiveTranslation
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/active_translation/application_helper.rb

@@ -0,0 +1,4 @@
+module ActiveTranslation
+  module ApplicationHelper
+  end
+end

data/app/jobs/active_translation/application_job.rb

@@ -0,0 +1,4 @@
+module ActiveTranslation
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/lib/active_translation/google_translate.rb

@@ -0,0 +1,52 @@
+# USAGE: GoogleTranslate.translate(target_language_code: "es-MX", text: "Hello world!")
+# USAGE: GoogleTranslate.translate(target_language_code: "es-MX", text: Job.posted_status.last.title, obj: Job.posted_status.last)
+# @see https://cloud.google.com/translate/docs/basic/translating-text
+
+module ActiveTranslation
+  class GoogleTranslate
+    class << self
+      def translate(target_language_code:, text:, source: "en-US", obj: nil)
+        conn = Faraday.new(url: "https://translation.googleapis.com/") do |faraday|
+          faraday.request :json
+          faraday.response :json
+          faraday.request :authorization, "Bearer", -> { token }
+        end
+
+        response =
+          conn.post(
+            "language/translate/v2",
+            {
+              q: text,
+              target: target_language_code,
+              source: source,
+            }
+          )
+
+        return nil unless response.success?
+
+        parse_response(response)
+      end
+
+      private
+
+      def parse_response(response)
+        response.body.dig("data", "translations", 0, "translatedText")
+        # CGI.unescapeHTML(translation) if translation.is_a?(String)
+      end
+
+      def token
+        return "fake_access_token" if Rails.env.test?
+
+        Rails.cache.fetch("google_access_token", expires_in: 55.minutes) do
+          google_oauth_credentials = ActiveTranslation.configuration.to_json
+          authorizer = Google::Auth::ServiceAccountCredentials.make_creds(
+            json_key_io: StringIO.new(google_oauth_credentials),
+            scope: [ "https://www.googleapis.com/auth/cloud-platform" ]
+          )
+          authorizer.fetch_access_token!
+          authorizer.access_token
+        end
+      end
+    end
+  end
+end

data/app/mailers/active_translation/application_mailer.rb

@@ -0,0 +1,6 @@
+module ActiveTranslation
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/active_translation/application_record.rb

@@ -0,0 +1,5 @@
+module ActiveTranslation
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/active_translation/translation.rb

@@ -0,0 +1,13 @@
+module ActiveTranslation
+  class Translation < ApplicationRecord
+    belongs_to :translatable, polymorphic: true
+
+    validates :locale, presence: true, uniqueness: { scope: [ :translatable_type, :translatable_id ] }
+
+    serialize :translated_attributes, coder: JSON
+
+    def outdated?
+      source_checksum != translatable.translation_checksum
+    end
+  end
+end

data/app/views/layouts/active_translation/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Active translations</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "active_translation/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+ActiveTranslation::Engine.routes.draw do
+end

data/lib/active_translation/configuration.rb

@@ -0,0 +1,29 @@
+module ActiveTranslation
+  class Configuration
+    attr_accessor :type,
+      :project_id,
+      :private_key_id,
+      :private_key,
+      :client_email,
+      :client_id,
+      :auth_uri,
+      :token_uri,
+      :auth_provider_x509_cert_url,
+      :client_x509_cert_url,
+      :universe_domain
+
+    def initialize
+      @type = nil
+      @project_id = nil
+      @private_key_id = nil
+      @private_key = nil
+      @client_email = nil
+      @client_id = nil
+      @auth_uri = "https://accounts.google.com/o/oauth2/auth"
+      @token_uri = "https://oauth2.googleapis.com/token"
+      @auth_provider_x509_cert_url = "https://www.googleapis.com/oauth2/v1/certs"
+      @client_x509_cert_url = nil
+      @universe_domain = "googleapis.com"
+    end
+  end
+end

data/lib/active_translation/engine.rb

@@ -0,0 +1,11 @@
+module ActiveTranslation
+  class Engine < ::Rails::Engine
+    isolate_namespace ActiveTranslation
+
+    initializer "active_translation.model" do
+      ActiveSupport.on_load(:active_record) do
+        include ActiveTranslation::Translatable
+      end
+    end
+  end
+end

data/lib/active_translation/translatable.rb

@@ -0,0 +1,230 @@
+module ActiveTranslation
+  module Translatable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def translates(*attributes, manual: [], into:, unless: nil, if: nil)
+        @translation_config ||= {}
+        @translation_config[:attributes] = Array(attributes).map(&:to_s)
+        @translation_config[:manual_attributes] = Array(manual).map(&:to_s)
+        @translation_config[:locales] = into
+        @translation_config[:unless] = binding.local_variable_get(:unless)
+        @translation_config[:if] = binding.local_variable_get(:if)
+
+        has_many :translations, class_name: "ActiveTranslation::Translation", as: :translatable, dependent: :destroy
+
+        delegate :translation_config, to: :class
+        delegate :translatable_attribute_names, to: :class
+
+        after_commit :translate_if_needed, on: [ :create, :update ]
+
+        # Respond to calls for manual attribute retrieval (model.fr_attribute)
+        # Respond to calls for manual attribute assignment (model.fr_attribute = "Bonjour")
+        # Respond to calls such as fr_translation or de_translation
+        # Respond to calls such as model.name(locale: :fr)
+        define_method(:method_missing) do |method_name, *args, &block|
+          super() unless method_name.to_s.split("_").size == 2
+
+          locale = method_name.to_s.split("_").first
+          attribute = method_name.to_s.split("_").last
+
+          if translation_config[:manual_attributes].include? attribute
+            translation = translations.find_by(locale: locale)
+            return read_attribute(attribute) unless translation
+
+            translation.translated_attributes[attribute].presence || read_attribute(attribute)
+          elsif attribute.last == "=" && translation_config[:manual_attributes].include?(attribute.delete("="))
+            attribute.delete!("=")
+            translation = translations.find_or_initialize_by(locale: locale.to_s)
+            attrs = translation.translated_attributes ? translation.translated_attributes : {}
+            attrs[attribute] = args.first
+            translation.translated_attributes = attrs
+            translation.save!
+          elsif attribute == "translation" || translation_config[:attributes].include?(attribute)
+            translations.find_by(locale: locale)
+          end
+        end
+
+        # Override attribute methods so that they accept a locale argument (defaulting to current I18n locale)
+        attributes.each do |attr|
+          define_method(attr) do |locale: I18n.locale|
+            if locale && translation = translations.find_by(locale: locale.to_s)
+              translation.translated_attributes&.dig attr.to_s || super()
+            else
+              super()
+            end
+          end
+        end
+
+        # Override manual attribute methods so that they accept a locale argument (defaulting to current I18n locale)
+        Array(manual).each do |attr|
+          define_method("#{attr}") do |locale: I18n.locale|
+            if locale && translation = translations.find_by(locale: locale.to_s)
+              translation.translated_attributes[attr.to_s].presence || read_attribute(attr)
+            else
+              read_attribute(attr)
+            end
+          end
+        end
+      end
+
+      def translatable_attribute_names
+        translation_config[:attributes]
+      end
+
+      def translation_config
+        @translation_config
+      end
+    end
+
+    def fully_translated?(attribute_types = :auto)
+      case attribute_types
+      when :auto, :auto_only
+        !translations_missing?
+      when :manual, :manual_only
+        !manual_translations_missing?
+      when :all, :include_manual
+        !translations_missing? && !manual_translations_missing?
+      else
+        raise ArgumentError, "acceptable arguments are [:auto, :auto_only, :manual, :manual_only, :all, :include_manual]"
+      end
+    end
+
+    def manual_translations_missing?
+      return false unless conditions_met?
+
+      translatable_locales.each do |locale|
+        translation_config[:manual_attributes].each do |attribute|
+          next if read_attribute(attribute).blank?
+
+          return true unless translation = translations.find_by(locale: locale)
+          return true unless translation.translated_attributes.keys.include?(attribute)
+        end
+      end
+
+      false
+    end
+
+    def outdated_translations
+      translations.select { _1.outdated? }
+    end
+
+    def translatable_locales
+      case translation_config[:locales]
+      when Symbol
+        if translation_config[:locales] == :all
+          I18n.available_locales - [ I18n.default_locale ]
+        else
+          send(translation_config[:locales])
+        end
+      when Proc
+        instance_exec(&translation_config[:locales])
+      when Array
+        translation_config[:locales]
+      end
+    end
+
+    def translate_if_needed
+      translations.delete_all and return unless conditions_met?
+
+      return unless translatable_attributes_changed? || condition_checks_changed? || translations_outdated? || translations_missing?
+
+      translatable_locales.each do |locale|
+        translation = translations.find_or_create_by(locale: locale.to_s)
+
+        if translation.new_record? || translation.outdated?
+          TranslationJob.perform_later(self, locale.to_s, translation_checksum)
+        end
+      end
+    end
+
+    def translate!
+      translatable_locales.each do |locale|
+        TranslationJob.perform_later(self, locale.to_s, translation_checksum)
+      end
+    end
+
+    def translate_now!(locales = translatable_locales)
+      Array(locales).each do |locale|
+        TranslationJob.perform_now(self, locale.to_s, translation_checksum)
+      end
+    end
+
+    def translation_checksum
+      values = translatable_attribute_names.map { |attr| read_attribute(attr).to_s }
+      Digest::MD5.hexdigest(values.join)
+    end
+
+    # translations are "missing" if they are not manual, the translatable attribute isn't blank
+    # and there's no translation for that attribute for all locales
+    def translations_missing?
+      return false unless conditions_met?
+
+      translatable_locales.each do |locale|
+        translatable_attribute_names.each do |attribute|
+          next if read_attribute(attribute).blank?
+
+          return true unless translation = translations.find_by(locale: locale)
+          return true unless translation.translated_attributes.keys.include?(attribute)
+        end
+      end
+
+      false
+    end
+
+    def translations_outdated?
+      return false unless conditions_met?
+      return true if translations.map(&:outdated?).any?
+
+      false
+    end
+
+    private
+
+    def condition_checks_changed?
+      saved_changes.any? && conditions_exist? && conditions_met?
+    end
+
+    def conditions_exist?
+      return true if translation_config[:if] || translation_config[:unless]
+
+      false
+    end
+
+    # returns true if all conditions are met, or if there are no conditions
+    def conditions_met?
+      if_condition_met? && unless_condition_met?
+    end
+
+    def evaluate_condition(condition)
+      case condition
+      when Symbol
+        send(condition)
+      when Proc
+        instance_exec(&condition)
+      when nil
+        true
+      else
+        false
+      end
+    end
+
+    # returns true if condition is met or there is no condition
+    def if_condition_met?
+      return true unless translation_config[:if]
+
+      evaluate_condition(translation_config[:if])
+    end
+
+    def translatable_attributes_changed?
+      saved_changes.any? && saved_changes.keys.intersect?(translatable_attribute_names)
+    end
+
+    # returns true if condition is met or there is no condition
+    def unless_condition_met?
+      return true unless translation_config[:unless]
+
+      !evaluate_condition(translation_config[:unless])
+    end
+  end
+end

data/lib/active_translation/translation_job.rb

@@ -0,0 +1,36 @@
+module ActiveTranslation
+  class TranslationJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(object, locale, checksum)
+      translated_data = {}
+
+      object.translatable_attribute_names.each do |attribute|
+        source_text = object.read_attribute(attribute)
+        translated_data[attribute.to_s] = translate_text(source_text, locale)
+      end
+
+      translation = object.translations
+        .find_or_initialize_by(
+          locale: locale,
+        )
+
+      existing_data = translation.translated_attributes.present? ? translation.translated_attributes : {}
+
+      merged_attributes = existing_data.merge(translated_data)
+
+      translation.update!(
+        translated_attributes: merged_attributes,
+        source_checksum: checksum
+      )
+    end
+
+    private
+
+    def translate_text(text, target_locale)
+      return "[#{target_locale}] #{text}" if Rails.env.test?
+
+      ActiveTranslation::GoogleTranslate.translate(target_language_code: target_locale, text: text)
+    end
+  end
+end

data/lib/active_translation/version.rb

@@ -0,0 +1,3 @@
+module ActiveTranslation
+  VERSION = "0.7.1"
+end

data/lib/active_translation.rb

@@ -0,0 +1,21 @@
+require "active_translation/version"
+require "active_translation/engine"
+require "active_translation/configuration"
+require "active_translation/translatable"
+require "active_translation/translation_job"
+require "faraday"
+require "googleauth"
+
+module ActiveTranslation
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/generators/active_translation/install_generator.rb

@@ -0,0 +1,26 @@
+module ActiveTranslation
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migration
+        migration_template "create_translations.rb", "db/migrate/create_translations.rb"
+      end
+
+      def copy_initializer
+        template "active_translation.rb", "config/initializers/active_translation.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/active_translation/templates/README

@@ -0,0 +1,19 @@
+===============================================================================
+
+Active Translations has been installed!
+
+Next steps:
+
+1. Run migrations:
+   rails db:migrate
+
+2. Configure your Google Translation API key:
+   # config/initializers/active_translation.rb
+   ActiveTranslation.configure do |config|
+     config.google_api_key = ENV['GOOGLE_TRANSLATION_API_KEY']
+   end
+
+3. Add to your models:
+   translates :name, :description, into: [:es, :fr]
+
+===============================================================================

data/lib/generators/active_translation/templates/active_translation.rb

@@ -0,0 +1,14 @@
+ActiveTranslation.configure do |config|
+  config.project_id = ENV.fetch("GOOGLE_TRANSLATION_PROJECT_ID", :missing_google_translation_project_id)
+  config.private_key_id = ENV.fetch("GOOGLE_TRANSLATION_PRIVATE_KEY_ID", :missing_google_translation_private_key_id)
+  config.private_key = ENV.fetch("GOOGLE_TRANSLATION_PRIVATE_KEY", :missing_google_translation_private_key)
+  config.client_email = ENV.fetch("GOOGLE_TRANSLATION_CLIENT_EMAIL", :missing_google_translation_client_email)
+  config.client_id = ENV.fetch("GOOGLE_TRANSLATION_CLIENT_ID", :missing_google_translation_client_id)
+  config.client_x509_cert_url = ENV.fetch("GOOGLE_TRANSLATION_CLIENT_CERT_URL", :missing_google_translation_client_cert_url)
+
+  config.type = ENV.fetch("GOOGLE_TRANSLATION_TYPE", "service_account")
+  config.auth_uri = ENV.fetch("GOOGLE_TRANSLATION_AUTH_URI", "https://accounts.google.com/o/oauth2/auth")
+  config.token_uri = ENV.fetch("GOOGLE_TRANSLATION_TOKEN_URI", "https://oauth2.googleapis.com/token")
+  config.auth_provider_x509_cert_url = ENV.fetch("GOOGLE_TRANSLATION_AUTH_PROVIDER_CERT_URL", "https://www.googleapis.com/oauth2/v1/certs")
+  config.universe_domain = ENV.fetch("GOOGLE_TRANSLATION_UNIVERSE_DOMAIN", "googleapis.com")
+end

data/lib/generators/active_translation/templates/create_translations.rb

@@ -0,0 +1,14 @@
+class CreateTranslations < ActiveRecord::Migration[7.0]
+  def change
+    create_table :active_translation_translations do |t|
+      t.references :translatable, polymorphic: true, null: false
+      t.string :locale, null: false
+      t.text :translated_attributes
+      t.string :source_checksum
+      t.timestamps
+    end
+
+    add_index :active_translation_translations, [ :translatable_type, :translatable_id, :locale ],
+      unique: true, name: "index_translations_on_translatable_and_locale"
+  end
+end

data/lib/tasks/active_translation_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :active_translation do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: active_translation
+version: !ruby/object:Gem::Version
+  version: 0.7.1
+platform: ruby
+authors:
+- Sean Hogge
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: googleauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Easily translate specific attributes of any ActiveRecord model
+email:
+- sean@seanhogge.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/active_translation/application.css
+- app/controllers/active_translation/application_controller.rb
+- app/helpers/active_translation/application_helper.rb
+- app/jobs/active_translation/application_job.rb
+- app/lib/active_translation/google_translate.rb
+- app/mailers/active_translation/application_mailer.rb
+- app/models/active_translation/application_record.rb
+- app/models/active_translation/translation.rb
+- app/views/layouts/active_translation/application.html.erb
+- config/routes.rb
+- lib/active_translation.rb
+- lib/active_translation/configuration.rb
+- lib/active_translation/engine.rb
+- lib/active_translation/translatable.rb
+- lib/active_translation/translation_job.rb
+- lib/active_translation/version.rb
+- lib/generators/active_translation/install_generator.rb
+- lib/generators/active_translation/templates/README
+- lib/generators/active_translation/templates/active_translation.rb
+- lib/generators/active_translation/templates/create_translations.rb
+- lib/tasks/active_translation_tasks.rake
+homepage: https://github.com/seanhogge/active_translation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seanhogge/active_translation
+  source_code_uri: https://github.com/seanhogge/active_translation
+  changelog_uri: https://github.com/seanhogge/active_translation
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Easily translate specific attributes of any ActiveRecord model
+test_files: []