inertia_i18n 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5d21515efb4733bc47d4a1f7b4964768893478366e101bfd4209c4cd45f3fee
+  data.tar.gz: fd44f198a5d66b793459eac5ab9b0b43487e3c4d4abc9b5f1e2145a995ceacd3
+SHA512:
+  metadata.gz: a54935ae8c875ba3b9baf3fadab5bc7033150da97eb72ed7c453b7dd14e315809df3cfc7ac58cf5f34eb0a426b1343a9cfe206da45e897a93e4ac20edc957b12
+  data.tar.gz: 02f8b5b053cf02be28186c79a137935d83fd55c82c7e27f1c7a9531c46803e16a5aab8d8748f4c46576800f7322ce755c99154d26ae2c350360d7efbf95f6011

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-06
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Poimtsev
+
+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,418 @@
+# InertiaI18n
+
+Translation management for Inertia.js applications with Rails backend
+
+[![Gem Version](https://badge.fury.io/rb/inertia_i18n.svg)](https://badge.fury.io/rb/inertia_i18n)
+[![Build Status](https://github.com/alec-c4/inertia_i18n/workflows/CI/badge.svg)](https://github.com/alec-c4/inertia_i18n/actions)
+
+## The Problem
+
+Inertia.js applications have a split architecture:
+
+- **Backend (Rails):** Uses YAML locale files (`config/locales/*.yml`)
+- **Frontend (React/Svelte/Vue):** Uses i18next JSON files
+
+This creates several challenges:
+
+1. **Duplicate management:** Maintaining translations in two formats
+2. **Sync issues:** Keys in YAML but missing in JSON (or vice versa)
+3. **No usage tracking:** Unused translation keys accumulate
+4. **Manual process:** Converting YAML → JSON by hand is error-prone
+
+Existing tools like [i18n-tasks](https://github.com/glebm/i18n-tasks) only handle Rails/backend translations.
+
+## The Solution
+
+InertiaI18n provides:
+
+- **YAML → JSON conversion** with interpolation mapping (`%{var}` → `{{var}}`)
+- **AST-based scanning** to find translation usage in `.svelte`, `.tsx`, `.vue` files
+- **Health checks** to detect missing, unused, and unsynchronized keys
+- **Watch mode** for automatic regeneration during development
+- **Rails integration** via initializers and rake tasks
+
+**One source of truth:** Rails YAML files, with JSON auto-generated.
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'inertia_i18n'
+```
+
+Run the installer:
+
+```bash
+rails generate inertia_i18n:install
+```
+
+This generator will:
+
+1. Create the locale directory structure (`config/locales/frontend`, `config/locales/backend`).
+2. Generate the configuration file (`config/initializers/inertia_i18n.rb`).
+3. Create a sample locale file.
+4. Detect your frontend framework (React, Vue, or Svelte) and add necessary dependencies (e.g., `react-i18next`) to your `package.json`.
+
+---
+
+## Recommended Directory Structure
+
+To avoid conflicts between backend and frontend translation keys, it is recommended to separate your locale files into subdirectories:
+
+```
+config/
+└── locales/
+    ├── backend/      # Rails-specific translations
+    │   ├── en.yml
+    │   └── ru.yml
+    ├── frontend/     # Frontend-specific translations
+    │   ├── common.en.yml
+    │   ├── pages.en.yml
+    │   └── pages.ru.yml
+    └── en.yml          # Optional: shared or legacy keys
+```
+
+By default, InertiaI18n will look for YAML files in `config/locales/frontend`. You can customize this using the `source_paths` configuration.
+
+---
+
+## Quick Start
+
+### 1. Configure
+
+The installer creates a default configuration file. You can customize it in `config/initializers/inertia_i18n.rb`.
+
+```ruby
+# config/initializers/inertia_i18n.rb
+InertiaI18n.configure do |config|
+  # Recommended: point to a dedicated frontend folder
+  config.source_paths = [Rails.root.join('config', 'locales', 'frontend')]
+
+  config.target_path = Rails.root.join('app', 'frontend', 'locales')
+  config.locales = [:en, :ru]
+
+  # Scan paths are automatically set based on your detected framework
+  config.scan_paths = [
+    Rails.root.join('app', 'frontend', '**', '*.{svelte,tsx,vue}')
+  ]
+end
+```
+
+### 2. Convert YAML to JSON
+
+```bash
+# One-time conversion
+bundle exec rake inertia_i18n:convert
+
+# Watch mode (auto-convert on YAML changes)
+bundle exec rake inertia_i18n:watch
+```
+
+### 3. Check Translation Health
+
+The recommended way to check translation health is by running the generated test as part of your test suite. See the [CI Integration](#ci-integration) section for details.
+
+You can also run a manual check from the command line:
+
+```bash
+# Find missing, unused, and out-of-sync keys
+bundle exec rake inertia_i18n:health
+```
+
+---
+
+## CLI Usage
+
+All CLI commands load the Rails environment, so they have access to your application's configuration and behave identically to the `rake` tasks.
+
+```bash
+# Generate a new configuration file
+inertia_i18n init
+
+# Convert YAML to JSON
+inertia_i18n convert
+
+# Convert specific locale
+inertia_i18n convert --locale=ru
+
+# Scan frontend code for translation usage
+inertia_i18n scan
+
+# Check translation health
+inertia_i18n health
+```
+
+---
+
+## Features
+
+### YAML → JSON Conversion
+
+**Input (Rails YAML):**
+
+```yaml
+# config/locales/en.yml
+en:
+  user:
+    greeting: "Hello, %{name}!"
+    items:
+      one: "1 item"
+      other: "%{count} items"
+```
+
+**Output (i18next JSON):**
+
+```json
+{
+  "user": {
+    "greeting": "Hello, {{name}}!",
+    "items_one": "1 item",
+    "items_other": "{{count}} items"
+  }
+}
+```
+
+### Smart Scanning
+
+Detects translation usage in:
+
+- Svelte: `{t('key')}` and `t('key')` in `<script>`
+- React: `{t('key')}` in JSX
+- Vue: `{{ t('key') }}` and `t('key')` in script
+
+Handles:
+
+- Static keys: `t('user.greeting')`
+- Template literals: `t(\`user.\${type}.title\`)` (flagged for review)
+- Dynamic patterns: `t(keyVariable)` (flagged for review)
+
+### Health Checks
+
+| Check            | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| **Missing Keys** | Used in code but not in JSON (breaks app)        |
+| **Unused Keys**  | In JSON but never used (bloat)                   |
+| **Locale Sync**  | Key exists in `en.json` but missing in `ru.json` |
+
+### Watch Mode
+
+Auto-regenerates JSON when YAML files change:
+
+```bash
+bundle exec rake inertia_i18n:watch
+
+# Output:
+👀 Watching config/locales for YAML changes...
+📝 Detected locale file changes...
+   Changed: config/locales/hr.en.yml
+🔄 Regenerating JSON files...
+✅ Done!
+```
+
+---
+
+## CI Integration
+
+The best way to ensure your translations stay healthy is to check them in your Continuous Integration (CI) pipeline.
+
+### Test-based Health Check (Recommended)
+
+Generate a dedicated test file that runs the health check as part of your test suite:
+
+```bash
+# For RSpec
+rails g inertia_i18n:test
+# Creates spec/inertia_i18n_health_spec.rb
+
+# For Minitest
+# Creates test/inertia_i18n_health_test.rb
+```
+
+Now, your existing CI command will automatically catch translation issues:
+
+```bash
+# Run your full test suite
+bundle exec rspec
+# or
+bundle exec rails test
+```
+
+When issues are found, the test will fail with a detailed report:
+
+```
+Failure/Error: fail message.join("\n")
+
+RuntimeError:
+
+  Translation health check failed!
+
+  Missing Keys (1):
+    - home.title
+
+  Unused Keys (1):
+    - unused.key
+
+  Locale Synchronization Issues (2):
+    - unused.key (in ru)
+    - home.title (in ru)
+```
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      # Run the full test suite, which now includes the translation health check
+      - name: Run tests
+        run: bundle exec rspec
+```
+
+---
+
+## Compatibility with i18n-tasks
+
+If you use [i18n-tasks](https://github.com/glebm/i18n-tasks) for your backend translations, it might flag your frontend keys as "unused" or "missing". To prevent this, configure `i18n-tasks` to ignore the frontend locale directory.
+
+Add this to your `config/i18n-tasks.yml`:
+
+```yaml
+# config/i18n-tasks.yml
+data:
+  read:
+    - "config/locales/backend/**/*.yml" # Read only backend locales
+    - "config/locales/*.yml" # Optional: shared keys
+```
+
+Alternatively, you can exclude the frontend directory:
+
+```yaml
+# config/i18n-tasks.yml
+ignore:
+  - "frontend.*" # Ignore all keys starting with "frontend." (if namespaced)
+```
+
+---
+
+## Configuration Reference
+
+```ruby
+InertiaI18n.configure do |config|
+  # Source directories for your frontend YAML files.
+  # Default: ['config/locales/frontend']
+  config.source_paths = [
+    'config/locales/frontend',
+    'config/locales/common'
+  ]
+  config.source_pattern = '**/*.{yml,yaml}'
+
+  # Target: i18next JSON files
+  config.target_path = 'app/frontend/locales'
+
+  # Locales to process
+  config.locales = [:en, :ru, :de]
+
+  # Frontend paths to scan
+  config.scan_paths = [
+    'app/frontend/**/*.{js,ts,jsx,tsx,svelte,vue}'
+  ]
+
+  # Interpolation conversion
+  config.interpolation = { from: '%{', to: '{{' }
+
+  # Flatten nested keys (default: false)
+  config.flatten_keys = false
+
+  # Ignore patterns (don't scan these files)
+  config.ignore_patterns = [
+    '**/node_modules/**',
+    '**/vendor/**',
+    '**/*.test.{js,ts}'
+  ]
+end
+```
+
+---
+
+## Comparison with Alternatives
+
+| Feature                 | InertiaI18n | i18n-tasks        | i18next-parser       |
+| ----------------------- | ----------- | ----------------- | -------------------- |
+| Rails YAML support      | ✅          | ✅                | ❌                   |
+| i18next JSON support    | ✅          | ❌                | ✅                   |
+| YAML → JSON conversion  | ✅          | ❌                | ❌                   |
+| Frontend usage scanning | ✅          | ❌                | ✅ (extraction only) |
+| Missing keys detection  | ✅          | ✅ (backend only) | ✅ (frontend only)   |
+| Unused keys detection   | ✅          | ✅ (backend only) | ❌                   |
+| Locale sync check       | ✅          | ✅                | ✅                   |
+| Watch mode              | ✅          | ❌                | ✅                   |
+| Rails integration       | ✅          | ✅                | ❌                   |
+| Inertia.js specific     | ✅          | ❌                | ❌                   |
+
+**InertiaI18n = i18n-tasks + i18next-parser + YAML↔JSON bridge**
+
+---
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/alec-c4/inertia_i18n.git
+cd inertia_i18n
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run locally in your Rails app
+# Add to Gemfile:
+gem 'inertia_i18n', path: '../inertia_i18n'
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests (TDD approach)
+4. Implement the feature
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt)
+
+---
+
+## Credits
+
+Created by [Alexey Poimtsev](https://alec-c4.com)
+
+Inspired by:
+
+- [i18n-tasks](https://github.com/glebm/i18n-tasks) - Rails i18n management
+- [i18next-parser](https://github.com/i18next/i18next-parser) - Frontend key extraction
+- Real-world pain from managing translations in Inertia.js apps

data/exe/inertia_i18n

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.new
+loader.push_dir(File.expand_path("../lib", __dir__))
+loader.setup
+
+# Load Rails environment if available
+if File.exist?("config/environment.rb")
+  require "rails"
+  require File.expand_path("config/environment.rb")
+end
+
+require "inertia_i18n/cli"
+
+InertiaI18n::Cli.start(ARGV)

data/lib/generators/inertia_i18n/install_generator.rb

@@ -0,0 +1,102 @@
+require "rails/generators"
+require "json"
+
+module InertiaI18n
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs InertiaI18n, creates directory structure, and adds frontend dependencies."
+
+      def check_dependencies
+        @framework = detect_framework
+      end
+
+      def create_directory_structure
+        say "Creating locale directory structure...", :green
+        empty_directory "config/locales/frontend"
+        empty_directory "config/locales/backend"
+        empty_directory "app/frontend/locales"
+      end
+
+      def move_existing_locales
+        # Move standard Rails locales to backend if they exist in the root
+        %w[en.yml ru.yml].each do |file|
+          source = "config/locales/#{file}"
+          if File.exist?(source)
+            say "Moving #{file} to config/locales/backend/", :yellow
+            rename_file source, "config/locales/backend/#{file}"
+          end
+        end
+      end
+
+      def create_sample_locales
+        copy_file "common.en.yml", "config/locales/frontend/common.en.yml"
+      end
+
+      def create_initializer
+        template "inertia_i18n.rb.tt", "config/initializers/inertia_i18n.rb"
+      end
+
+      def add_frontend_dependencies
+        packages_to_add = ["i18next"]
+
+        case @framework
+        when :react
+          say "Detected React. Adding react-i18next...", :green
+          packages_to_add << "react-i18next"
+        when :vue
+          say "Detected Vue. Adding i18next-vue...", :green
+          packages_to_add << "i18next-vue"
+        when :svelte
+          say "Detected Svelte.", :green
+        end
+
+        return unless File.exist?("package.json")
+
+        # Detect package manager
+        cmd = if File.exist?("yarn.lock")
+          "yarn add"
+        elsif File.exist?("bun.lockb")
+          "bun add"
+        else
+          "npm install"
+        end
+
+        run "#{cmd} #{packages_to_add.join(" ")}"
+      end
+
+      def show_post_install_info
+        say "\n✅ InertiaI18n installed successfully!", :green
+        say "\nNext steps:", :bold
+        say "1. Import and initialize i18next in your frontend application (e.g., app/frontend/i18n.js)."
+        say "2. Use the generated locales in config/locales/frontend/."
+        say "3. Run `bundle exec inertia_i18n convert` to generate the initial JSON files."
+        say "4. Start your server and happy translating!\n\n"
+      end
+
+      private
+
+      def detect_framework
+        return unless File.exist?("package.json")
+
+        package_json = JSON.parse(File.read("package.json"))
+        dependencies = package_json["dependencies"] || {}
+        dev_dependencies = package_json["devDependencies"] || {}
+        all_deps = dependencies.merge(dev_dependencies)
+
+        if all_deps.key?("react")
+          :react
+        elsif all_deps.key?("vue")
+          :vue
+        elsif all_deps.key?("svelte")
+          :svelte
+        end
+      end
+
+      def rename_file(old_name, new_name)
+        FileUtils.mv(old_name, new_name)
+      end
+    end
+  end
+end

data/lib/generators/inertia_i18n/templates/common.en.yml

@@ -0,0 +1,6 @@
+en:
+  common:
+    welcome: "Welcome to InertiaI18n!"
+    actions:
+      save: "Save"
+      cancel: "Cancel"

data/lib/generators/inertia_i18n/templates/i18n_spec.rb

@@ -0,0 +1,33 @@
+require "rails_helper"
+require "inertia_i18n/health_checker"
+require "inertia_i18n/file_converter"
+
+RSpec.describe InertiaI18n::HealthChecker do
+  it "has healthy translations" do
+    # Ensure JSON files are up-to-date before checking
+    InertiaI18n::FileConverter.convert_all
+
+    checker = described_class.new.check!
+
+    return if checker.healthy?
+
+    message = ["\nTranslation health check failed!"]
+
+    if checker.issues[:missing].any?
+      message << "\nMissing Keys (#{checker.issues[:missing].count}):"
+      checker.issues[:missing].each { |i| message << "  - #{i[:key]}" }
+    end
+
+    if checker.issues[:unused].any?
+      message << "\nUnused Keys (#{checker.issues[:unused].count}):"
+      checker.issues[:unused].each { |i| message << "  - #{i[:key]}" }
+    end
+
+    if checker.issues[:unsync].any?
+      message << "\nLocale Synchronization Issues (#{checker.issues[:unsync].count}):"
+      checker.issues[:unsync].each { |i| message << "  - #{i[:key]} (in #{i[:locale]})" }
+    end
+
+    expect(checker.healthy?).to be(true), message.join("\n")
+  end
+end

data/lib/generators/inertia_i18n/templates/i18n_test.rb

@@ -0,0 +1,31 @@
+require "test_helper"
+require "inertia_i18n/health_checker"
+require "inertia_i18n/file_converter"
+
+class I18nTest < ActiveSupport::TestCase
+  test "translations are healthy" do
+    # Ensure JSON files are up-to-date before checking
+    InertiaI18n::FileConverter.convert_all
+
+    checker = InertiaI18n::HealthChecker.new.check!
+
+    message = ["\nTranslation health check failed!"]
+
+    if checker.issues[:missing].any?
+      message << "\nMissing Keys (#{checker.issues[:missing].count}):"
+      checker.issues[:missing].each { |i| message << "  - #{i[:key]}" }
+    end
+
+    if checker.issues[:unused].any?
+      message << "\nUnused Keys (#{checker.issues[:unused].count}):"
+      checker.issues[:unused].each { |i| message << "  - #{i[:key]}" }
+    end
+
+    if checker.issues[:unsync].any?
+      message << "\nLocale Synchronization Issues (#{checker.issues[:unsync].count}):"
+      checker.issues[:unsync].each { |i| message << "  - #{i[:key]} (in #{i[:locale]})" }
+    end
+
+    assert checker.healthy?, message.join("\n")
+  end
+end

data/lib/generators/inertia_i18n/templates/inertia_i18n.rb.tt

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+InertiaI18n.configure do |config|
+  # Source directories for your frontend YAML files.
+  config.source_paths = [Rails.root.join("config", "locales", "frontend")]
+
+  # Target path for generated i18next JSON files
+  config.target_path = Rails.root.join("app", "frontend", "locales")
+
+  # Locales to process (first is primary)
+  config.locales = %i[en]
+
+  # YAML file pattern to match
+  config.source_pattern = "**/*.{yml,yaml}"
+
+  # Paths to scan for translation usage
+  <% extensions = case @framework
+     when :react then "js,ts,jsx,tsx"
+     when :vue then "js,ts,vue"
+     when :svelte then "js,ts,svelte"
+     else "js,ts,jsx,tsx,svelte,vue"
+     end %>
+  config.scan_paths = [
+    "app/frontend/**/*.{<%= extensions %>}"
+  ]
+
+  # Interpolation conversion (Rails %{var} -> i18next {{var}})
+  config.interpolation = { from: "%{", to: "{{" }
+
+  # Dynamic key patterns (prefix => description)
+  # Keys matching these prefixes won't be marked as unused
+  config.dynamic_patterns = {
+    # "status." => "Dynamic status keys"
+  }
+
+  # Keys to ignore during unused check
+  config.ignore_unused = []
+
+  # Keys to ignore during missing check
+  config.ignore_missing = []
+end