active_record-translated 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d359bbfb6e7b356977ec10452c42131aa680559399023ffcffd0980b625135ae
+  data.tar.gz: 947a046dcfedab49d567160b1cc9240e1c7a49b11fca0b3bc2bb06ccf78e000b
+SHA512:
+  metadata.gz: a58f249814f5390e80e2a6e1637134515767c2f8c635374e183051d6c6f5ef580f758b1f78be9c51e40c771d93129df844542b01537ce20b69dd1caea243cbe1
+  data.tar.gz: 176e32b5c73a13ee06df807d10d96acecd4bc9df7ee5f329133833d9e9f80d0377bb5277af6a472d672a3bcb05b2305e8c43a20ddba1c846a6538135f07916d7

data/README.md

@@ -0,0 +1,249 @@
+active_record-translated
+========
+
+[![RuboCop](https://github.com/kjellberg/active_record-translated/actions/workflows/rubocop.yml/badge.svg)](https://github.com/kjellberg/active_record-translated/actions/workflows/rubocop.yml)
+[![RSpec](https://github.com/kjellberg/active_record-translated/actions/workflows/rspec.yml/badge.svg)](https://github.com/kjellberg/active_record-translated/actions/workflows/rspec.yml)
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+
+This gem tackles localization of ActiveRecord models in Ruby on Rails by keeping records in different languages within the same database table. Translations are separated by a `locale`-column and linked together with an indexed `record_id`-column.
+
+Since all database rows now are language-specific, this approach works best for models where **all or most of the attributes should be translatable**. Or else you may end up with a lot of duplicated data. For a visual example, check out examples further down this readme.
+
+### Guidelines
+
+These are the guidlines we should follow when developing this gem:
+
+- Should work without any modifications to current application code.
+- Should not decrease performance with multiple SQL queries.
+- Should act like a normal record if no locale is set.
+- Should accept an unlimited number of languages without decreased performance caused by this gem.
+- Should not brake current specs/tests.
+- Should not brake model validations
+- All translations will have it's own record.
+- Translations of the same object should have the same `record_id`
+- A translation should know all other available translations with the same `record_id`
+- Should work independently on what type (int/uuid..) of primary key the database table is using.
+
+Installation
+------------
+
+Add the following line to Gemfile:
+
+```ruby
+gem "active_record-translated", github: 'kjellberg/active_record-translated'
+```
+
+and run `bundle install` from your terminal to install it.
+
+Getting started
+---------------
+
+To generate the initializer and default configuration, run:
+
+```console
+rails generate translated:install
+```
+
+*This will create an initializer at `config/initializers/active_record-translated.rb`*
+
+### Make a model translatable
+
+To enable translation for a model, run:
+
+```console
+rails generate translated MODEL
+```
+
+*This will generate a database migration for the `locale` and `record_id` attributes and setup your model for translation.*
+
+Examples
+--------
+
+The `posts` table below represents a translated `Post` model with the attributes `title` and `slug`. Note that `resource_id` and `locale` was created by this gem when you generated the migrations.
+
+<table>
+  <thead>
+    <th>id</th>
+    <th>resource_id</th>
+    <th>locale</th>
+    <th>title</th>
+    <th>slug</th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>42fb060d-2000-4a73-bb74-cfb5ca799e0d</td>
+      <td>en</td>
+      <td>Good morning!</td>
+      <td>a-blog-post</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>42fb060d-2000-4a73-bb74-cfb5ca799e0d</td>
+      <td>es</td>
+      <td>Buenos días!</td>
+      <td>una-publicacion-de-blog</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>160f6aee-ba2d-4c7e-a273-96b99468c8f9</td>
+      <td>en</td>
+      <td>Good night!</td>
+      <td>another-blog-post</td>
+    </tr>
+    <tr>
+      <td>4</td>
+      <td>160f6aee-ba2d-4c7e-a273-96b99468c8f9</td>
+      <td>es</td>
+      <td>Buenas noches!</td>
+      <td>otra-entrada</td>
+    </tr>
+  </tbody>
+</table>
+
+Your model may look something like this:
+
+```ruby
+# app/models/post.rb
+
+class Post < ApplicationRecord
+  # Enable translations for this model
+  include ActiveRecord::Translated::Model
+  
+  # You can keep using validations the same way you did before installing this gem. The only
+  # difference is that validations will be run on all translations separately.
+  #
+  # Examples:
+  #  - Title must exist on each translation.
+  #  - Every translation should have it's unique slug.
+  validates :title, presence: true
+  validates :slug, presence: true, uniqueness: true
+end
+```
+
+### Create a new record
+
+The creation of a new record will autmatically generate a unique `record_id` and set the `locale` attribute to the current locale. The current locale is determined globally by `I18n.locale` and/or within the gem via `ActiveRecord::Translated.locale`, the latter with greater priority. The default locale if nothing is set is `:en`.
+
+```ruby
+before_action do
+  I18n.locale = :en_US # fallback if "ActiveRecord::Translated.locale" is not set
+  ActiveRecord::Translated.locale = :en_UK # has priority over "I18n.locale"
+end
+
+# POST /posts/create
+def create
+  @post = Post.create(title: "A post!", ...)
+
+  @post.id # => 5
+  @post.record_id # => 448ecc54-cc82-4c24-aed4-89fae5d38ec4 (auto-generated)
+  @post.locale # => :en_UK
+  ...
+end
+```
+
+### Create a new record in a specific language
+
+To create a post in a language other than the current locale, just pass a language code to the `locale` attribute.
+
+```ruby
+post = Post.create(title: "Una entrada de blog", ..., locale: :es)
+post.locale # => :es
+```
+
+#### Using #with_locale
+
+You can also wrap your code inside `ActiveRecord::Translated#with_locale`. This will temporary override the current locale within the block.
+
+```ruby
+post = ActiveRecord::Translated.with_locale(:es) do
+  Post.create(title: "Una entrada de blog", ...)
+end
+
+post.locale # => :es
+```
+
+### Create a new translation of an existing record
+
+To translate an already existing post, create a second post with a different `locale` and add it to the first post via `#translations`. This will make sure that our two translations are linked together with a shared `record_id`.
+
+```ruby
+# Create an english post
+post = Post.create(title: "A post!", ...)
+
+# Create a spanish translation
+post_es = Post.create(title: "Una entrada de blog", ..., locale: :es)
+
+# Associate the Spanish translation with the english post
+post.translations << post_es
+
+# Record ID should match:
+post.record_id # => 448ecc54-cc82-4c24-aed4-89fae5d38ec4
+post_es.record_id # => 448ecc54-cc82-4c24-aed4-89fae5d38ec4
+
+# Locale should differ:
+post.locale # => :en
+post_es.locale # => :es
+```
+
+### Fetch a translated record
+
+Your translated model will automatically scope query results by the current locale. For example, with `I18n.locale` set to `:sv`, your model will only return Swedish results. There's some different ways to fetch translations from the database using ActiveRecord's #find:
+
+#### Find by primary key
+
+The first and most obvious way is to just query a translation by its primary key. If you already now the ID, just do a normal #find:
+
+```ruby
+I18n.locale = :en # Ignored by #find when fetching a record by its unique primary key.
+
+post = Post.find(4) # English translation
+post_es = Post.find(5) # Spanish translation
+
+post.locale # => :en
+post_es.locale #=> :es
+```
+
+#### Find by record_id
+
+You can also find a translated record by using a record_id as the argument. This will look for a row that matches both the record_id and the current locale:
+
+```ruby
+I18n.locale = :es
+
+post = Post.find("0e048f11-0ad9-48f1-b493-36e1f01d7994") 
+post_es.locale #=> :es
+```
+
+License
+-------
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Contributing
+------------
+
+New contributors are very welcome and needed. This gem is an open-source, community project that anyone can contribute to. Reviewing and testing is highly valued and the most effective way you can contribute as a new contributor. It also will teach you much more about the code and process than opening pull requests.
+
+Except for testing, there are several ways you can contribute to the betterment of the project:
+
+- **Report an issue?** - If the issue isn’t reported, we can’t fix it. Please report any bugs, feature, and/or improvement requests on the [GitHub Issues tracker](https://github.com/kjellberg/active_record-translated/issues).
+- **Submit patches** - Do you have a new feature or a fix you'd like to share? [Submit a pull request](https://github.com/kjellberg/active_record-translated/pulls)!
+- **Write blog articles** - Are you using this gem? We'd love to hear how you're using it in your projects. Write a tutorial and post it on your blog!
+
+### Development process
+
+The `main` branch is regularly built and tested, but it is not guaranteed to be completely stable. Tags are created regularly from release branches to indicate new official, stable release versions of the libraries.
+
+### Commit message guidelines
+
+A good commit message should describe what changed and why. This project uses [semantic commit messages](https://www.conventionalcommits.org/en/v1.0.0/) to streamline the release process. Before a pull request can be merged, it must have a pull request title with a semantic prefix.
+
+### Versioning
+
+This application aims to adhere to [Semantic Versioning](http://semver.org/). Violations
+of this scheme should be reported as bugs. Specifically, if a minor or patch
+version is released that breaks backward compatibility, that version should be
+immediately yanked and/or a new version should be immediately released that
+restores compatibility. Breaking changes to the public API will only be
+introduced with new major versions.

data/lib/active_record/translated/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Translated
+    # Makes Translated available to Rails as an Engine.
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/active_record/translated/model.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Translated
+    # Makes Translated available to Rails as an Engine.
+    module Model
+      extend ActiveSupport::Concern
+
+      # rubocop:disable Metrics/BlockLength
+      included do
+        before_save :set_record_id
+        before_save :set_locale
+
+        has_many :translations, -> { global }, class_name: "Post", foreign_key: :record_id, primary_key: :record_id
+        default_scope { where(locale: ActiveRecord::Translated.locale) }
+        scope :global, -> { unscope(where: :locale) }
+
+        class << self
+          def find(*args)
+            id = args.first
+
+            return find_translated(id) if ActiveRecord::Translated.record_id?(id)
+
+            super(*args)
+          end
+
+          def exists?(id)
+            return super unless ActiveRecord::Translated.record_id?(id)
+            return true if exists_translated?(id)
+
+            super
+          end
+
+          private
+
+          def find_translated(record_id, allow_nil: false)
+            result = find_by(record_id: record_id)
+            return result if result
+
+            raise ActiveRecord::RecordNotFound unless allow_nil
+          end
+
+          # rubocop:disable Rails/WhereExists
+          def exists_translated?(record_id)
+            where(record_id: record_id, locale: ActiveRecord::Translated.locale).exists?
+          end
+          # rubocop:enable Rails/WhereExists
+        end
+      end
+      # rubocop:enable Metrics/BlockLength
+
+      def set_locale
+        return if locale.present?
+
+        self.locale = ActiveRecord::Translated.locale
+      end
+
+      def set_record_id
+        return if record_id.present?
+
+        self.record_id = ActiveRecord::Translated.generate_record_id
+      end
+    end
+  end
+end

data/lib/active_record/translated/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# :nocov:
+module ActiveRecord
+  module Translated
+    VERSION = "0.1.1"
+  end
+end

data/lib/active_record/translated.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "active_record/translated/version"
+require "active_record/translated/engine"
+
+require "dry-configurable"
+require "request_store"
+require "securerandom"
+
+module ActiveRecord
+  module Translated
+    extend Dry::Configurable
+
+    # Defaults to nil if no default value is given
+    setting :default_locale, default: nil
+
+    autoload :Model, "active_record/translated/model"
+
+    class << self
+      def generate_record_id
+        SecureRandom.uuid.split("-")[1..3].join("-")
+      end
+
+      def record_id?(string)
+        return false unless string.is_a?(String)
+
+        string.match(/^[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}$\z/)
+      end
+
+      def locale
+        read_locale || config.default_locale || I18n.locale || :en
+      end
+
+      def locale=(locale)
+        set_locale(locale)
+      end
+
+      def with_locale(locale)
+        previous_locale = read_locale
+        begin
+          set_locale(locale)
+          yield(locale)
+        ensure
+          set_locale(previous_locale)
+        end
+      end
+      # @!endgroup
+
+      protected
+
+      def read_locale
+        storage[:art_locale]
+      end
+
+      # rubocop:disable Naming/AccessorMethodName
+      def set_locale(locale)
+        locale = locale.to_sym if locale.is_a?(String)
+        storage[:art_locale] = locale
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      def storage
+        RequestStore.store
+      end
+    end
+  end
+end

data/lib/tasks/active_record/translated_tasks.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# desc "Explaining what the task does"
+# task :active_record_translated do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: active_record-translated
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Rasmus Kjellberg
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-11-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+- !ruby/object:Gem::Dependency
+  name: net-smtp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.3
+- !ruby/object:Gem::Dependency
+  name: request_store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/active_record/translated.rb
+- lib/active_record/translated/engine.rb
+- lib/active_record/translated/model.rb
+- lib/active_record/translated/version.rb
+- lib/tasks/active_record/translated_tasks.rake
+homepage: https://github.com/kjellberg/active_record-translated
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/kjellberg/active_record-translated/issues
+  documentation_uri: https://github.com/kjellberg/active_record-translated/issues
+  source_code_uri: https://github.com/kjellberg/active_record-translated
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Separate database records for each language, grouped together with an ID
+test_files: []