awesome_jsonb_translate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ffa6732fc05182186a76341a8c1335d428c1b74686109eefba62e64aae6723f4
+  data.tar.gz: 5c723ede13d6091434835a1c341804cff94f38e4cb855a6e996d2c9f61b66d49
+SHA512:
+  metadata.gz: 21b0933074aa9548332a4ba764fbf26a7223c4e9003a38298c75a12c31d7a40fda0c2ea0719e7a3ed4352ac56a28a42d47540e2afa247447d0937595fe80f156
+  data.tar.gz: 9ca4739aa48e62e8e0c7ef7181bdba9c93da8bf73861aaec1f119a1c65adadc0f601bac20ef7d2b393e89f127e9472ea2151e58c5480ee74254b6c64e63087a1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 firedev.com
+
+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,292 @@
+# Awesome JSONB Translate
+
+This gem uses PostgreSQL's JSONB datatype and ActiveRecord models to translate model data.
+
+- No extra columns or tables needed to operate
+- Clean naming in the database model
+- Everything is well tested
+- Uses modern JSONB type for better performance and flexibility
+- Falls back to default locale
+
+## Features
+
+- [x] `v0.1.0` It works
+
+## Requirements
+
+- I18n
+- PostgreSQL with JSONB support (9.4+)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'awesome_jsonb_translate'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install awesome_jsonb_translate
+
+## Usage
+
+Include `AwesomeJsonbTranslate` in your model class.
+
+Use `translates` in your models, to define the attributes, which should be translateable:
+
+
+```rb
+class Model < ApplicationRecord
+  include AwesomeJsonbTranslate
+  translates :title, :description
+end
+```
+
+---
+
+## Examples of Supported Usage
+
+### Assigning and Retrieving Translations
+
+```ruby
+p = Page.new(title_en: 'English title', title_de: 'Deutscher Titel')
+p = Page.new(title: { en: 'English title', de: 'Deutscher Titel'})
+p.title_en # => 'English title'
+p.title_de # => 'Deutscher Titel'
+
+I18n.with_locale(:en) { p.title } # => 'English title'
+I18n.with_locale(:de) { p.title } # => 'Deutscher Titel'
+```
+
+### Fallbacks
+
+It always falls back to default locale
+
+```ruby
+# Behavior with fallbacks enabled
+p = Page.new(title_en: 'English title')
+I18n.with_locale(:de) { p.title } # => 'English title' (falls back to English)
+
+# Behavior with empty string
+p = Page.new(title_en: 'English title', title_de: '')
+I18n.with_locale(:de) { p.title } # => 'English title' (falls back since German is empty)
+```
+
+### Assigning a Hash Directly
+
+```ruby
+p = Page.new(title: { en: 'English title', de: 'Deutscher Titel' })
+p.title_raw # => { 'en' => 'English title', 'de' => 'Deutscher Titel' }
+```
+
+### Locale Accessors
+
+```ruby
+p.title_en = 'Updated English title'
+p.title_de = 'Aktualisierter Deutscher Titel'
+```
+
+### Querying by Translated Value (JSONB-aware)
+
+```ruby
+# Find records by current locale value
+Page.find_by(title_en: 'English title')
+
+# which transforms to
+Page.where("title->>'en' = ?", 'English title') # queries current locale
+
+# Use with other conditions
+Page.find_by(title_en: 'English title', author: 'John')
+
+# which transforms to
+Page.where("title->>'en' = ?", 'English title').where(author: 'John')
+```
+
+### Finding or Initializing Records
+
+```ruby
+# Find existing record by translated attribute
+Page.find_or_initialize_by(title_en: 'English title')
+
+# Initialize new record if not found
+new_page = Page.find_or_initialize_by(title_en: 'New Page', slug: 'new')
+new_page.persisted? # => false
+
+# Find with combined attributes
+Page.find_or_initialize_by(title_en: 'English title', slug: 'english-title')
+
+# Find or create records
+existing = Page.find_or_create_by(title_en: 'English title')
+new_record = Page.find_or_create_by(title_en: 'Brand New', slug: 'brand-new') # Creates and saves the record
+```
+
+### Ordering Records
+
+```ruby
+# Sort by translated field in current locale
+Page.order("title->>'en' ASC")
+```
+
+### Other Useful Methods
+
+```ruby
+# List translated attributes
+Page.translated_attributes # => [:title, :content]
+
+# List all accessor methods
+Page.translated_accessors # => [:title_en, :title_de, :content_en, :content_de]
+
+# Check translation presence
+page.translated?(:title) # => true
+page.translated?(:title, :fr) # => false
+
+# Check translation availability
+page.translation_available?(:title, :en) # => true
+
+# Get all locales that have a translation
+page.available_translations(:title) # => ["en", "de"]
+
+# Get all available locales for the record
+page.available_locales # => [:en, :de]
+```
+
+---
+
+```ruby
+class Page < ActiveRecord::Base
+  include AwesomeJsonbTranslate
+  translates :title, :content
+end
+```
+
+Make sure that the datatype of this columns is `jsonb`:
+
+```ruby
+class CreatePages < ActiveRecord::Migration
+  def change
+    create_table :pages do |t|
+      t.column :title, :jsonb
+      t.column :content, :jsonb
+      t.timestamps
+    end
+  end
+end
+```
+
+Use the model attributes per locale:
+
+```ruby
+p = Page.create(title_en: "English title", title_de: "Deutscher Titel")
+
+I18n.locale = :en
+p.title # => English title
+
+I18n.locale = :de
+p.title # => Deutscher Titel
+
+I18n.with_locale :en do
+  p.title # => English title
+end
+```
+
+The raw data is available via the suffix `_raw`:
+
+```ruby
+p = Page.new(title: {en: 'English title', de: 'Deutscher Titel'})
+
+p.title_raw # => {'en' => 'English title', 'de' => 'Deutscher Titel'}
+```
+
+### Find
+
+`awesome_jsonb_translate` created a `find_by` helper.
+
+```ruby
+Page.create!(:title_en => 'English title', :title_de => 'Deutscher Titel')
+Page.create!(:title_en => 'Another English title', :title_de => 'Noch ein Deutscher Titel')
+
+Page.find_by(title_en: 'English title')  # => Find by a specific language
+```
+
+### To Param
+
+For generating URLs with translated slugs:
+
+```ruby
+class Page < ActiveRecord::Base
+  translates :title
+
+  def to_param
+    # Or use parameterize for URL-friendly slugs
+    title_en.parameterize
+  end
+end
+```
+
+### Limitations
+
+`awesome_jsonb_translate` patches ActiveRecord, which create the limitation, that a with `where` chained `first_or_create` and `first_or_create!` **doesn't work** as expected.
+Here is an example, which **won't** work:
+
+```ruby
+Page.where(title_en: 'Titre français').first_or_create!
+```
+
+A workaround is:
+
+```ruby
+Page.find_or_create_by(title_en: 'Titre français')
+```
+
+## Development
+
+```
+bundle
+bin/setup
+bundle exec rspec
+```
+
+## Testing
+
+To run the tests:
+
+1. Ensure PostgreSQL is installed and running
+2. Set up the test environment:
+
+```bash
+bin/setup
+```
+
+This script will:
+- Install required gem dependencies
+- Create the PostgreSQL test database if it doesn't exist
+
+3. Run the tests:
+
+```bash
+bundle exec rspec
+```
+
+You can also set custom database connection details with environment variables:
+
+```bash
+DB_NAME=custom_db_name DB_USER=your_username DB_PASSWORD=your_password bundle exec rspec
+```
+
+## Troubleshooting
+
+If you encounter issues running tests:
+
+1. Make sure PostgreSQL is installed and running
+2. Ensure the user has permissions to create databases
+3. Check that the database 'awesome_jsonb_translate_test' exists or can be created
+4. Run `bin/setup` to prepare the test environment
+5. For more detailed database errors, run with debug flag:
+   ```bash
+   DB_DEBUG=true bundle exec rspec
+   ```

data/lib/awesome_jsonb_translate/active_record.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module AwesomeJsonbTranslate
+  module ActiveRecord
+    def translates(*attrs)
+      include InstanceMethods
+
+      class_attribute :translated_attributes, :translated_accessors, :translation_options
+      self.translated_attributes = attrs.map(&:to_sym)
+      self.translated_accessors = translated_attributes.flat_map do |attr_name|
+        I18n.available_locales.map do |locale|
+          ["#{attr_name}_#{locale}", "#{attr_name}_#{locale}="]
+        end
+      end.flatten.map(&:to_sym)
+      self.translation_options = {}
+
+      attrs.each do |attr_name|
+        define_translation_accessors(attr_name)
+        define_translation_writer(attr_name)
+        define_translation_reader(attr_name)
+        define_raw_accessor(attr_name)
+      end
+
+      extend FindByMethods
+    end
+
+    def define_translation_accessors(attr_name)
+      I18n.available_locales.each do |locale|
+        define_translation_reader_for_locale(attr_name, locale)
+        define_translation_writer_for_locale(attr_name, locale)
+      end
+    end
+
+    def define_translation_reader_for_locale(attr_name, locale)
+      define_method("#{attr_name}_#{locale}") do
+        read_translation(attr_name, locale)
+      end
+    end
+
+    def define_translation_writer_for_locale(attr_name, locale)
+      define_method("#{attr_name}_#{locale}=") do |value|
+        write_translation(attr_name, locale, value)
+      end
+    end
+
+    def define_translation_reader(attr_name)
+      define_method(attr_name) do
+        read_translation(attr_name, I18n.locale)
+      end
+    end
+
+    def define_translation_writer(attr_name)
+      define_method("#{attr_name}=") do |value|
+        normalized_value = value.is_a?(Hash) ? value.stringify_keys : { I18n.locale.to_s => value }
+        write_attribute(attr_name, (send("#{attr_name}_raw") || {}).merge(normalized_value))
+      end
+    end
+
+    def define_raw_accessor(attr_name)
+      define_method("#{attr_name}_raw") do
+        raw_value = read_attribute(attr_name)
+        raw_value.is_a?(Hash) ? raw_value : {}
+      end
+    end
+
+    module InstanceMethods
+      def translated?(attr_name, locale = I18n.locale)
+        value = read_translation_without_fallback(attr_name, locale)
+        translation_available?(attr_name, locale) && value.present?
+      end
+
+      def translation_available?(attr_name, locale = I18n.locale)
+        self.class.translated_attributes.include?(attr_name.to_sym) &&
+          send("#{attr_name}_raw").key?(locale.to_s)
+      end
+
+      def available_translations(attr_name)
+        return [] unless self.class.translated_attributes.include?(attr_name.to_sym)
+
+        send("#{attr_name}_raw").keys
+      end
+
+      def available_locales
+        locales = self.class.translated_attributes.flat_map do |attr_name|
+          available_translations(attr_name)
+        end.uniq
+        locales.map(&:to_sym)
+      end
+
+      def read_translation(attr_name, locale)
+        translations = send("#{attr_name}_raw")
+        value = translations[locale.to_s]
+
+        if value.blank? && locale != I18n.default_locale
+          translations[I18n.default_locale.to_s]
+        else
+          value
+        end
+      end
+
+      def read_translation_without_fallback(attr_name, locale)
+        translations = send("#{attr_name}_raw")
+        translations[locale.to_s]
+      end
+
+      def write_translation(attr_name, locale, value)
+        translations = send("#{attr_name}_raw").dup
+        translations[locale.to_s] = value
+        write_attribute(attr_name, translations)
+      end
+    end
+
+    module FindByMethods
+      # Override find_by to handle translated attributes
+      def find_by(attributes)
+        # Check if any of the keys represent translated attributes
+        has_translated_attrs = attributes.keys.any? do |key|
+          translated_accessors.include?(key.to_sym)
+        end
+
+        # If no translated attributes, use default implementation
+        return super unless has_translated_attrs
+
+        translated_attrs = {}
+        regular_attrs = {}
+
+        attributes.each do |key, value|
+          key_s = key.to_s
+          if key_s.include?('_') && !key_s.end_with?('=')
+            parts = key_s.split('_')
+            locale = parts.last
+            attr_name = parts[0..-2].join('_')
+
+            if translated_attributes.include?(attr_name.to_sym)
+              translated_attrs[attr_name] ||= {}
+              translated_attrs[attr_name][locale] = value
+            else
+              regular_attrs[key] = value
+            end
+          else
+            regular_attrs[key] = value
+          end
+        end
+
+        scope = where(regular_attrs)
+
+        translated_attrs.each do |attr_name, locales|
+          locales.each do |locale, value|
+            scope = scope.where("#{attr_name}->>'#{locale}' = ?", value)
+          end
+        end
+
+        scope.first
+      end
+
+      # Override find_or_initialize_by to handle translated attributes
+      def find_or_initialize_by(attributes)
+        result = find_by(attributes)
+        return result if result
+
+        # If no record found, initialize with the given attributes
+        new_record = new
+        new_record.assign_attributes(attributes)
+        new_record
+      end
+
+      # Override find_or_create_by to handle translated attributes
+      def find_or_create_by(attributes)
+        result = find_by(attributes)
+        return result if result
+
+        # If no record found, create with the given attributes
+        create(attributes)
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.extend AwesomeJsonbTranslate::ActiveRecord

data/lib/awesome_jsonb_translate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AwesomeJsonbTranslate
+  VERSION = '0.1.0'
+end

data/lib/awesome_jsonb_translate.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'awesome_jsonb_translate/version'
+require 'awesome_jsonb_translate/active_record'
+
+module AwesomeJsonbTranslate
+  # Just serve as a namespace
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: awesome_jsonb_translate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Your Name
+bindir: bin
+cert_chain: []
+date: 2025-04-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: This gem uses PostgreSQL's JSONB datatype to store and retrieve translations
+  for ActiveRecord models without extra columns or tables
+email:
+- your.email@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/awesome_jsonb_translate.rb
+- lib/awesome_jsonb_translate/active_record.rb
+- lib/awesome_jsonb_translate/version.rb
+homepage: https://github.com/username/awesome_jsonb_translate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/username/awesome_jsonb_translate
+  source_code_uri: https://github.com/username/awesome_jsonb_translate/tree/master
+  documentation_uri: https://github.com/username/awesome_jsonb_translate/blob/master/README.md
+  changelog_uri: https://github.com/username/awesome_jsonb_translate/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: ActiveRecord translations using PostgreSQL's JSONB data type
+test_files: []