internationalize 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ba5df71bafb02b68108aed602ac75ad4ced036109e49dbd40dc90354a7c351a
-  data.tar.gz: d39b4232e8b76511d1a409d6848fa98e8f60f8f9523b62985c467cb2767ec7e3
+  metadata.gz: 3f85c4969fc4c969bf8ad61c4cbdb76a5364c90b4c7853a446aaeb6a4ac629ff
+  data.tar.gz: 83c19c5597f26d23634cc37f3aaede5d7a58c62460c6a2cd5295a1d3e43c3017
 SHA512:
-  metadata.gz: 8ff4adb5021405380a123cc1cc06b8dd3818851e32570ae90e7bdf776f566bbc9ff6504ab26960dae909109550444875aaca42d3cf988ae4393b18c05628e292
-  data.tar.gz: 8d2643b882281a39f0446d274b25321be03909c2ba41510a75a4e498918fc0ee37a59abae42e373e246a4d1b1f1ebeefdb5ec9e12e29d8a81a13c3d05f9478a6
+  metadata.gz: 02037bac922bbd2e7a7ccf82399e5892436a32f02970c87365935745ebc2858b16b4befbf11b26a9e70e54833ae0347a3d45a8450c839a95d93111dc92109035
+  data.tar.gz: 7dced1dca63327c7e66c527be390ac39bff028615f10696094b545514573000a52962fdbd807a77e7bb823b4c6151c56284b075e18be37bbea36d4140e10450d

data/context/configuration.md

@@ -0,0 +1,83 @@
+# Internationalize: Configuration
+
+## Global Configuration
+
+```ruby
+# config/initializers/internationalize.rb
+Internationalize.configure do |config|
+  # Override fallback locale (defaults to I18n.default_locale)
+  config.fallback_locale = :en
+
+  # Override available locales (defaults to I18n.available_locales)
+  config.available_locales = [:en, :de, :fr, :es]
+end
+```
+
+## Per-Attribute Configuration
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+
+  # With fallback (default)
+  international :title
+
+  # Without fallback
+  international :description, fallback: false
+end
+```
+
+## Database Setup
+
+Use the generator to create migrations:
+
+```bash
+rails generate internationalize:translation Article title description
+```
+
+Or create migrations manually:
+
+### SQLite / MySQL
+
+```ruby
+class AddTranslationsToArticles < ActiveRecord::Migration[7.1]
+  def change
+    add_column :articles, :title_translations, :json, default: {}
+  end
+end
+```
+
+### PostgreSQL
+
+For better query performance, use `jsonb`:
+
+```ruby
+class AddTranslationsToArticles < ActiveRecord::Migration[7.1]
+  def change
+    add_column :articles, :title_translations, :jsonb, default: {}
+
+    # Optional: Add GIN index for faster queries
+    add_index :articles, :title_translations, using: :gin
+  end
+end
+```
+
+## Supported Databases
+
+| Database | Minimum Version | JSON Type | Query Syntax |
+|----------|-----------------|-----------|--------------|
+| SQLite | 3.38+ | `json` | `json_extract()` |
+| PostgreSQL | 9.4+ | `json`/`jsonb` | `->>` operator |
+| MySQL | 8.0+ | `json` | `->>` operator |
+
+## I18n Integration
+
+Internationalize automatically uses Rails I18n settings:
+
+```ruby
+I18n.locale           # Used for current locale
+I18n.default_locale   # Used for fallbacks
+I18n.available_locales # Used for locale-specific accessors
+```
+
+Override these with the configuration options above if needed.

data/context/getting-started.md

@@ -0,0 +1,98 @@
+# Internationalize: Getting Started
+
+Internationalize is a lightweight internationalization gem for Rails that stores translations in JSON columns instead of separate tables.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "internationalize"
+```
+
+## Quick Setup
+
+### 1. Generate a migration for translation columns
+
+```bash
+rails generate internationalize:translation Article title description
+```
+
+This creates a migration adding `title_translations` and `description_translations` JSON columns.
+
+Or write the migration manually:
+
+```ruby
+class AddTranslationsToArticles < ActiveRecord::Migration[7.1]
+  def change
+    add_column :articles, :title_translations, :json, default: {}
+    add_column :articles, :description_translations, :json, default: {}
+  end
+end
+```
+
+### 2. Include the mixin and declare translatable attributes
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title, :description
+end
+```
+
+### 3. Use translations
+
+```ruby
+# Create with translations (hash for multiple locales)
+Article.international_create!(
+  title: { en: "Hello World", de: "Hallo Welt" },
+  status: "published"
+)
+
+# Or direct string for current locale
+I18n.locale = :de
+Article.international_create!(title: "Achtung!")  # Sets title_de
+
+# Set translation for current locale
+article.title = "Hello World"
+
+# Set for specific locale
+article.title_en = "Hello World"
+article.title_de = "Hallo Welt"
+
+# Read translation
+article.title         # => uses I18n.locale
+article.title_de      # => "Hallo Welt"
+
+# Access raw hash
+article.title_translations  # => {"en" => "Hello World", "de" => "Hallo Welt"}
+```
+
+### 4. Query translations
+
+```ruby
+# Exact match
+Article.international(title: "Hello World")
+
+# Partial match (LIKE)
+Article.international(title: "Hello", match: :partial)
+
+# Order by translation
+Article.international_order(:title, :desc)
+```
+
+## Key Concepts
+
+- Translations stored in `*_translations` JSON columns
+- No JOINs - data lives in the same table
+- Automatic fallback to default locale
+- Works with SQLite, PostgreSQL, and MySQL
+
+## Important: Column Defaults
+
+JSON columns **must** have `default: {}` set in the migration. The generator does this automatically, but if writing migrations manually, ensure you include it:
+
+```ruby
+add_column :articles, :title_translations, :json, default: {}
+```
+
+This is required for optimal performance and correct behavior.

data/context/index.yaml

@@ -0,0 +1,14 @@
+description: "Lightweight, performant internationalization for Rails using JSON columns"
+files:
+  - path: getting-started.md
+    title: "Getting Started"
+    description: "Quick setup guide for Internationalize"
+  - path: model-api.md
+    title: "Model API"
+    description: "Model mixin methods and generated accessors"
+  - path: query-api.md
+    title: "Query API"
+    description: "Query methods for searching and filtering translations"
+  - path: configuration.md
+    title: "Configuration"
+    description: "Global and per-attribute configuration options"

data/context/model-api.md

@@ -0,0 +1,101 @@
+# Internationalize: Model API
+
+## Including the Mixin
+
+```ruby
+class Article < ApplicationRecord
+  include Internationalize::Model
+  international :title, :description
+end
+```
+
+## Options
+
+```ruby
+# With fallback (default: true)
+international :title, fallback: true
+
+# Without fallback - returns nil if translation missing
+international :title, fallback: false
+```
+
+## Generated Instance Methods
+
+For each `international :title` declaration:
+
+### Accessors
+
+| Method | Description |
+|--------|-------------|
+| `title` | Get translation for current `I18n.locale` |
+| `title=` | Set translation for current `I18n.locale` |
+| `title?` | Check if translation exists |
+| `title_translations` | Get raw hash of all translations |
+| `title_translations=` | Set all translations at once |
+
+### Locale-Specific Accessors
+
+For each locale in `I18n.available_locales`:
+
+| Method | Description |
+|--------|-------------|
+| `title_en` | Get English translation directly |
+| `title_en=` | Set English translation |
+| `title_en?` | Check if English translation exists |
+| `title_de` | Get German translation |
+| `title_de=` | Set German translation |
+| ... | etc. for all locales |
+
+### Instance Helper Methods
+
+| Method | Description |
+|--------|-------------|
+| `set_translation(:title, :de, "Hallo")` | Set translation for attribute/locale |
+| `translation_for(:title, :de)` | Get translation without fallback |
+| `translated?(:title, :de)` | Check if translation exists |
+| `translated_locales(:title)` | Array of locales with translations |
+
+## Class Methods (Querying)
+
+All query methods default to current `I18n.locale` and return `ActiveRecord::Relation`:
+
+| Method | Description |
+|--------|-------------|
+| `international(**conditions, locale: nil)` | Exact match query |
+| `international_not(**conditions, locale: nil)` | Exclude matching records |
+| `international_search(**conditions, locale: nil, case_sensitive: false)` | Substring search |
+| `international_order(attr, dir = :asc, locale: nil)` | Order by translation |
+| `translated(*attrs, locale: nil)` | Find records with translation |
+| `untranslated(*attrs, locale: nil)` | Find records missing translation |
+
+```ruby
+# Examples
+Article.international(title: "Hello World")
+Article.international_search(title: "hello", locale: :de)
+Article.international_order(:title, :desc)
+Article.translated(:title, locale: :de)
+```
+
+## Class Attributes
+
+```ruby
+Article.international_attributes  # => [:title, :description]
+```
+
+## Fallback Behavior
+
+When `fallback: true` (default):
+
+```ruby
+article.title_en = "Hello"
+I18n.locale = :de
+article.title  # => "Hello" (falls back to default locale)
+```
+
+When `fallback: false`:
+
+```ruby
+article.title_en = "Hello"
+I18n.locale = :de
+article.title  # => nil
+```

data/context/query-api.md

@@ -0,0 +1,129 @@
+# Internationalize: Query API
+
+All query methods are class methods on models that include `Internationalize::Model`. They return `ActiveRecord::Relation` objects that can be chained with standard AR methods.
+
+## Default Locale Behavior
+
+All query methods default to the current `I18n.locale`. Use the `locale:` option to override:
+
+```ruby
+# Uses current I18n.locale
+Article.international(title: "Hello World")
+
+# Explicit locale
+Article.international(title: "Hallo Welt", locale: :de)
+```
+
+## Query Methods
+
+### international(**conditions, locale: nil)
+
+Exact match on translated attributes:
+
+```ruby
+Article.international(title: "Hello World")
+Article.international(title: "Hello", status: "published")
+Article.international(title: "Hallo Welt", locale: :de)
+```
+
+### international_not(**conditions, locale: nil)
+
+Exclude records matching conditions:
+
+```ruby
+Article.international_not(title: "Draft")
+Article.international_not(title: "Entwurf", locale: :de)
+```
+
+### international_search(**conditions, locale: nil, case_sensitive: false)
+
+Substring search (LIKE/ILIKE):
+
+```ruby
+# Case-insensitive (default)
+Article.international_search(title: "hello")
+Article.international_search(title: "hello", description: "world")
+
+# Case-sensitive
+Article.international_search(title: "Hello", case_sensitive: true)
+
+# With explicit locale
+Article.international_search(title: "welt", locale: :de)
+```
+
+### international_order(attribute, direction = :asc, locale: nil)
+
+Order by translated attribute:
+
+```ruby
+Article.international_order(:title)
+Article.international_order(:title, :desc)
+Article.international_order(:title, :asc, locale: :de)
+```
+
+### translated(*attributes, locale: nil)
+
+Find records with translations in specified locale:
+
+```ruby
+Article.translated(:title)
+Article.translated(:title, locale: :de)
+Article.translated(:title, :description, locale: :de)
+```
+
+### untranslated(*attributes, locale: nil)
+
+Find records missing translations:
+
+```ruby
+Article.untranslated(:title)
+Article.untranslated(:title, locale: :de)
+```
+
+## Chaining with ActiveRecord
+
+All methods return `ActiveRecord::Relation`, so they chain naturally with AR methods:
+
+```ruby
+Article.international(title: "Hello World")
+       .where(published: true)
+       .order(created_at: :desc)
+       .limit(10)
+       .includes(:author)
+```
+
+## Combining Multiple Queries
+
+Use `merge` to combine multiple international queries:
+
+```ruby
+# Search + filter + order
+Article.international_search(title: "hello")
+       .merge(Article.international(status: "published"))
+       .merge(Article.international_order(:title, :desc))
+
+# Query across multiple locales
+Article.international(title: "Hello World", locale: :en)
+       .merge(Article.international(title: "Hallo Welt", locale: :de))
+```
+
+## Examples
+
+```ruby
+# Find published articles with German title containing "Welt"
+Article.international_search(title: "Welt", locale: :de)
+       .where(published: true)
+       .merge(Article.international_order(:title, locale: :de))
+       .limit(10)
+
+# Find articles missing German translation
+Article.untranslated(:title, locale: :de).count
+
+# Complex multi-locale query - find articles with both EN and DE titles
+Article.translated(:title, locale: :en)
+       .merge(Article.translated(:title, locale: :de))
+
+# Exclude drafts and order by title
+Article.international_not(status: "draft")
+       .merge(Article.international_order(:title))
+```

data/lib/internationalize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Internationalize
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internationalize
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sampo Kuokkanen
@@ -49,6 +49,11 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- context/configuration.md
+- context/getting-started.md
+- context/index.yaml
+- context/model-api.md
+- context/query-api.md
 - lib/generators/internationalize/translation/templates/add_translations_migration.rb.erb
 - lib/generators/internationalize/translation_generator.rb
 - lib/internationalize.rb