i18n_proofreading 0.10.4 → 0.10.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3546b2ddcbb15b380075959eee5ea843e5c0e5cf52748101b0a1e57774365699
-  data.tar.gz: cb3bb010786b1d7f307c8cd850f372a8f9b5424765c26840d472f68ffe815eb8
+  metadata.gz: ca180baf5c569ccbce1681b0a26d914f7846225fef225ce0f3f5bb3a52b5e1f6
+  data.tar.gz: bbd44a938dcc053bc63d466cdca8b9ef65ec4360b8cabac2ac7e92b25304991f
 SHA512:
-  metadata.gz: 5e4b71924974509622d7c9d8d139e922fdd116ffded96f64ec6da94797cf09c96797328e6a76d12b169a99128a6de39f7daa48d67662bb513ee096ca4d865931
-  data.tar.gz: c729fef9100594e0fa53a7fcd81f5678eff7c2d8bc4b3cf56de1196e32f45997081e5e3f3080e065af3f8545388f4fe62d5f0cefbd43011f1103244bed678efe
+  metadata.gz: 7ff93f334e19313d03ee861c7da265fb8bb98047ca02e189a5d48e0660cc6012578da93508aa91b75dba64a8e4e70405a88a50ac935b93955771358fb3794399
+  data.tar.gz: 68f52f53cc1f2067a5f75920d282412de882463c394470276ac7495ba439d7a1a04f1fe0270b130b5bfbb706c6fc5893024e4829247bbd3624cf3de58641f714

data/AGENTS.md

@@ -0,0 +1,149 @@
+# AGENTS.md
+
+Instructions for coding agents. Two audiences:
+
+- **[Installing i18n_proofreading into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add in-context translation review or a way for someone to suggest better wording.
+- **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
+
+Requirements: Ruby >= 3.2, Rails >= 7.1. The widget needs the CSRF token from `csrf_meta_tags`, which a standard Rails layout already has.
+
+**Read this first: the gem never writes to your locale files, and it is not a production tool.** Both are deliberate, and both are covered below.
+
+If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show i18n_proofreading)/AGENTS.md"`.
+
+---
+
+## Installing into a Rails app
+
+### 1. Install
+
+```bash
+bundle add i18n_proofreading
+bin/rails generate i18n_proofreading:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/i18n_proofreading.rb`, one migration (`i18n_proofreading_suggestions`), and mounts the engine. Read the initializer it wrote — every option is documented there in comments, and it is the source of truth over any summary of it, including this file.
+
+### 2. There is no step 2 — do not edit the layout
+
+The widget injects itself into HTML responses through a Rack middleware, so **no layout change is needed**. Boot the app in development and look for the **"Suggest edits"** pill bottom-left. Click it, then click any text; `Esc` exits.
+
+Only if the host prefers to place it explicitly:
+
+```ruby
+config.auto_inject = false
+```
+
+```erb
+<%= i18n_proofreading_tag %>
+```
+
+Do not do both. And do not go looking for a missing `<%= … %>` when the pill does not appear — auto-injection is the default, so the cause is almost always the environment gate below.
+
+### 3. Before deploying: understand the two gates
+
+**a. Environments.** The tool is active only in `config.enabled_environments`, which defaults to `%w[development staging]`. In every other environment it does nothing at all: no key markers, no endpoint, and the I18n backend patch that marks keys is never even prepended. **Do not add `production` to that list to "let the client review the live site."** Marking every translated string in production is a user-visible change to every page, and the review endpoint is not built to be public.
+
+**b. The dashboard.** `/i18n_proofreading` defaults to **development only** and is independent of the widget gates, so a maintainer can triage from production while the widget stays off. It fails closed:
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+> **`enabled`, `authorize_admin` and `current_user` receive the raw `request`, not a controller.** Writing `->(request) { current_user }` is the most common mistake here — that method does not exist in this scope. Resolve the user *from the request*: Warden env, a signed cookie, `Current.user` if middleware already set it. `author_label` is the exception: it receives whatever `current_user` returned.
+
+### 4. Verify
+
+```bash
+bin/rails routes | grep i18n_proofreading    # engine mounted
+bin/rails i18n_proofreading:seed_demo        # optional sample suggestions, idempotent
+```
+
+Then in development: load a page, confirm the pill appears bottom-left, suggest a change to any string, and read it back at `/i18n_proofreading`.
+
+### The gem does not apply suggestions, and that is the point
+
+A suggestion is a row: the i18n key, the old value, the proposal, an optional comment, a locale, and a status (`pending` / `applied` / `rejected`). Nothing in the gem edits `config/locales/*.yml`, and **the dashboard is read-only — `index` and `show`, with no update or destroy action.** Applying a wording change means a human (or your own tooling) editing the YAML and committing it.
+
+So: **do not ask this gem to rewrite locale files, and do not build a "click to apply" button expecting an endpoint to exist.** If the app wants status bookkeeping, do it deliberately from your own code or the console — the enum is prefixed:
+
+```ruby
+I18nProofreading::Suggestion.status_pending.find(id).status_applied!
+```
+
+If you are asked to automate applying suggestions, that is host-app work: read the rows, write the YAML, review the diff in a pull request. Treat the suggestion table as an inbox, not as the source of truth for translations.
+
+### Turning suggest mode on from your own UI
+
+The pill is one way; a link is another, and the choice is remembered in a cookie so the rest of the app stays in suggest mode:
+
+```
+?i18n_proofreading=true    # on
+?i18n_proofreading=false   # off
+```
+
+`config.show_pill = false` hides the pill, `config.pill_label` overrides its text (nil = the localized `i18n_proofreading.pill` key), and `config.toggle_param` renames the parameter.
+
+### Do not
+
+- **Do not add `production` to `enabled_environments`** (see above).
+- **Do not copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** The middleware injects what is needed and the engine serves the code same-origin — which is what lets it run under a nonce-based CSP, including `strict-dynamic`, across Turbo body swaps.
+- **Do not edit the layout** for the default install — auto-injection is the default.
+- **Do not expect the gem to write YAML** (see above).
+- **Do not set config outside the initializer.** `rate_limit` in particular is read once when the controller class loads; assigning config per-request mutates it process-wide.
+
+### Configuration worth knowing
+
+Everything is optional; a fresh install works with zero config in development. Full list with comments is in the generated initializer.
+
+| Option | Default | Note |
+| --- | --- | --- |
+| `enabled_environments` | `%w[development staging]` | The hard gate. Never add production |
+| `enabled` | everyone | Per-request gate on top of the environment check |
+| `authorize_admin` | development only | **Who can read the dashboard.** Independent of the above |
+| `admin_layout` | `i18n_proofreading/application` | Render the dashboard in your admin shell |
+| `current_user` | `nil` | Receives the request |
+| `author_label` | email, else `to_s` | Receives the user |
+| `available_locales` | `I18n.available_locales` | Callable; validates what a suggestion may target |
+| `auto_inject` | `true` | `false` = place `i18n_proofreading_tag` yourself |
+| `show_pill`, `pill_label` | `true`, localized | Hide the pill and use `?i18n_proofreading=true` instead |
+| `toggle_param` | `"i18n_proofreading"` | Rename the query parameter |
+| `rate_limit` | `{ to: 30, within: 60 }` | Rails 7.2+; ignored on 7.1. `nil` disables |
+| `mount_path` | `"/i18n_proofreading"` | Keep in sync with the `mount` line |
+| `on_submit` | no-op | Runs inline after save — Slack, email, a ticket |
+
+The tool's own UI ships in 26 languages, RTL mirrored, and follows system light/dark.
+
+### Common failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| No pill, no outlines | The environment is not in `enabled_environments` (this is the usual one), or `config.enabled` returned false, or `show_pill = false` |
+| Pill appears but no strings are outlined | The I18n backend patch is only prepended in an enabled environment at boot — check you are actually in development/staging, and restart after changing the setting |
+| `/i18n_proofreading` returns a 403 | `authorize_admin` still at its development-only default |
+| Suggestions rejected with an invalid-token error | The layout is missing `csrf_meta_tags` |
+| A suggestion is rejected as an invalid locale | It must be in `config.available_locales` |
+| Nothing changes in the app after a suggestion is accepted | Expected. The gem never writes locale files — a human edits the YAML |
+| `undefined local variable current_user` in the initializer | A gate lambda treated its argument as a controller. It is a `request` |
+
+---
+
+## Working on the gem itself
+
+```bash
+bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rubocop              # must be clean
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test   # 7.1, 7.2, 8.0, 8.1 in gemfiles/
+```
+
+Layout: `app/` controller, `Suggestion`, dashboard views · `lib/i18n_proofreading/` config, middleware, the I18n marking backend, widget JS, seeds, engine · `lib/generators/i18n_proofreading/install/` the one generator · `config/locales/` 26 locales · `test/` minitest with `test/dummy` as the host app.
+
+Conventions this codebase holds to — follow them rather than the first thing that works:
+
+- **Production carries none of it.** The marking backend is prepended in `after_initialize` only when `environment_enabled?`, so a production boot never even patches I18n. Anything new must keep that property: no markers, no endpoint, no patch outside the enabled environments.
+- **The tool never writes to the host's locale files.** That is why there is deliberately no update or destroy route, and why the dashboard is read-only. Do not add an "apply" action that edits YAML.
+- **The widget is injected by middleware and served same-origin**, which is what keeps it working under a nonce-based CSP with `strict-dynamic` across Turbo body swaps. Do not inline it.
+- **Key marking must degrade to plain strings.** A host that reads translations outside a request, or in an environment where the tool is off, has to get ordinary values back.
+- Every user-facing change bumps `lib/i18n_proofreading/version.rb` and adds a `CHANGELOG.md` entry (Keep a Changelog format) that says what it costs, not only what it adds.
+- Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.10.6]
+
+- Added `AGENTS.md`: install and integration instructions written for coding
+  agents — that no layout change is needed because the widget is injected by
+  middleware, that the environment gate (never production) is the usual reason
+  the pill is missing, the request-shaped config lambdas, and above all that the
+  gem never writes to locale files, so there is no "apply" endpoint to build
+  against. It ships inside the gem, so
+  `cat "$(bundle show i18n_proofreading)/AGENTS.md"` works from a host app.
+- Corrected the `authorize_admin` comment in the configuration: it described the
+  dashboard as changing status and deleting, but the dashboard has been
+  read-only (`index` and `show` only) for as long as that route file has said so.
+
+## [0.10.5]
+
+- Added `config.admin_layout`, letting host apps render the proofreading
+  dashboard inside their own admin layout while keeping the standalone gem
+  layout as the default.
+
 ## [0.10.4]
 
 - Redesigned the proofreading admin dashboard into a two-column review layout

data/README.md

@@ -26,6 +26,16 @@ bin/rails generate i18n_proofreading:install
 bin/rails db:migrate
 ```
 
+Optional demo data:
+
+```bash
+bin/rails i18n_proofreading:seed_demo
+```
+
+It creates three idempotent sample suggestions across pending, applied, and
+rejected states. Running the task again refreshes those records instead of
+duplicating them.
+
 Boot the app in development and look for the **"Suggest edits"** pill in the
 bottom-left. Click it, then click any text. `Esc` exits.
 
@@ -39,6 +49,12 @@ No layout change needed — the widget injects itself into HTML responses.
 Ruby >= 3.2 · Rails >= 7.1 · CSRF token comes from `csrf_meta_tags`, already in
 a standard Rails layout.
 
+Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
+steps in the order an agent needs them, the gates it tends to get wrong, and the
+things it should not do (starting with: this gem never writes your locale files).
+It ships inside the gem, so `cat "$(bundle show i18n_proofreading)/AGENTS.md"`
+works from any app that bundles it.
+
 ## What you get
 
 |                |                                                                     |

data/app/controllers/i18n_proofreading/application_controller.rb

@@ -6,6 +6,10 @@ module I18nProofreading
 
     private
 
+    def i18n_proofreading_admin_layout
+      I18nProofreading.config.admin_layout
+    end
+
     # Gate for the widget's public API (submit a suggestion, read prior context).
     # The client can set the cookie, but it can never reach the endpoints unless
     # the app itself says the tool is available for this request.

data/app/controllers/i18n_proofreading/suggestions_controller.rb

@@ -9,7 +9,7 @@ module I18nProofreading
     before_action :require_admin, only: %i[index show]
     before_action :set_suggestion, only: :show
 
-    layout 'i18n_proofreading/application', only: %i[index show]
+    layout :i18n_proofreading_admin_layout, only: %i[index show]
 
     # Throttle the public submission endpoint per IP so one user or bot can't
     # flood the table. Uses the rate limiter built into Rails 7.2+ (backed by

data/lib/generators/i18n_proofreading/install/install_generator.rb

@@ -27,6 +27,7 @@ module I18nProofreading
 
       def post_install
         say "\ni18n_proofreading installed. Run `rails db:migrate`, then boot in development", :green
+        say 'Optional: run `bin/rails i18n_proofreading:seed_demo` for sample suggestions.'
         say "and look for the “Suggest edits” pill in the bottom-left corner.\n"
       end
 

data/lib/generators/i18n_proofreading/install/templates/initializer.rb

@@ -16,6 +16,11 @@ I18nProofreading.configure do |config|
   # development only; wire it to your own admin check to open it elsewhere.
   #
   # config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+  #
+  # Render the dashboard inside your app's admin layout. Default: the gem's
+  # standalone dashboard layout.
+  #
+  # config.admin_layout = "admin/application"
 
   # Attribute a suggestion to a user (optional). Return an object responding to
   # #id (ideally #email too), or nil. Receives the Rack::Request. You resolve the

data/lib/i18n_proofreading/configuration.rb

@@ -14,13 +14,19 @@ module I18nProofreading
     # feature flag, an allowlist, etc.
     attr_accessor :enabled
 
-    # Per-request gate for the triage dashboard (browse suggestions, change their
-    # status, delete). Independent of `enabled` and `enabled_environments`: the
+    # Per-request gate for the triage dashboard, which is read-only — browse and
+    # read suggestions; there is deliberately no update or destroy, since the
+    # tool never writes to the host's locale files.
+    # Independent of `enabled` and `enabled_environments`: the
     # widget is dev/staging-only, but a maintainer may want to triage from
     # production. Defaults to development only, so a fresh install never exposes
     # the dashboard until you wire it to your own admin check.
     attr_accessor :authorize_admin
 
+    # Layout used by the triage dashboard. Override this to render it inside
+    # your app's admin shell, e.g. "admin/application".
+    attr_accessor :admin_layout
+
     # Resolve the current user for attribution (optional). Return an object
     # responding to #id, or nil. Receives the Rack::Request.
     attr_accessor :current_user
@@ -68,6 +74,7 @@ module I18nProofreading
       @enabled_environments = %w[development staging]
       @enabled = ->(_request) { true }
       @authorize_admin = ->(_request) { Rails.env.development? }
+      @admin_layout = 'i18n_proofreading/application'
       @current_user = ->(_request) {}
       @author_label = ->(user) { user.respond_to?(:email) ? user.email : user&.to_s }
       @available_locales = -> { I18n.available_locales.map(&:to_s) }

data/lib/i18n_proofreading/engine.rb

@@ -4,6 +4,10 @@ module I18nProofreading
   class Engine < ::Rails::Engine
     isolate_namespace I18nProofreading
 
+    rake_tasks do
+      load File.expand_path('../tasks/i18n_proofreading_tasks.rake', __dir__)
+    end
+
     initializer 'i18n_proofreading.middleware' do |app|
       app.middleware.use I18nProofreading::Middleware
     end

data/lib/i18n_proofreading/seeds.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module I18nProofreading
+  module Seeds
+    SUGGESTIONS = [
+      {
+        translation_key: 'dashboard.title',
+        locale: 'en',
+        old_value: 'Dashboard',
+        proposed_value: 'Overview',
+        comment: 'Shorter and clearer for the first screen.',
+        page_url: '/dashboard',
+        status: 'pending',
+        author_id: 'i18n-proofreading-demo:reviewer',
+        author_label: 'Demo Reviewer'
+      },
+      {
+        translation_key: 'billing.cta',
+        locale: 'en',
+        old_value: 'Go',
+        proposed_value: 'Update billing details',
+        comment: 'The button should say what will happen.',
+        page_url: '/billing',
+        status: 'applied',
+        author_id: 'i18n-proofreading-demo:copywriter',
+        author_label: 'Demo Copywriter'
+      },
+      {
+        translation_key: 'settings.cancel',
+        locale: 'fr',
+        old_value: 'Annuler',
+        proposed_value: 'Supprimer le compte',
+        comment: 'Rejected example: this changes the meaning.',
+        page_url: '/settings',
+        status: 'rejected',
+        author_id: 'i18n-proofreading-demo:reviewer',
+        author_label: 'Demo Reviewer'
+      }
+    ].freeze
+
+    def self.load!
+      SUGGESTIONS.map do |attributes|
+        localized = attributes.merge(locale: locale_for(attributes.fetch(:locale)))
+        suggestion = I18nProofreading::Suggestion.find_or_initialize_by(
+          translation_key: localized.fetch(:translation_key),
+          locale: localized.fetch(:locale),
+          author_id: localized.fetch(:author_id)
+        )
+        suggestion.assign_attributes(localized)
+        suggestion.save!
+        suggestion
+      end
+    end
+
+    def self.locale_for(preferred)
+      locales = I18nProofreading.config.available_locales.call.map(&:to_s)
+      return preferred if locales.include?(preferred)
+
+      locales.first || I18n.default_locale.to_s
+    end
+    private_class_method :locale_for
+  end
+end

data/lib/i18n_proofreading/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18nProofreading
-  VERSION = '0.10.4'
+  VERSION = '0.10.6'
 end

data/lib/i18n_proofreading.rb

@@ -5,6 +5,7 @@ require 'i18n_proofreading/configuration'
 require 'i18n_proofreading/marking'
 require 'i18n_proofreading/widget'
 require 'i18n_proofreading/middleware'
+require 'i18n_proofreading/seeds'
 require 'i18n_proofreading/engine'
 
 # In-context translation proofreading for Rails. Renders each i18n key alongside

data/lib/tasks/i18n_proofreading_tasks.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :i18n_proofreading do
+  desc 'Create or refresh i18n_proofreading demo suggestions'
+  task seed_demo: :environment do
+    suggestions = I18nProofreading::Seeds.load!
+    puts "Seeded #{suggestions.size} i18n proofreading demo suggestions."
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: i18n_proofreading
 version: !ruby/object:Gem::Version
-  version: 0.10.4
+  version: 0.10.6
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -34,6 +34,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
 - MIT-LICENSE
 - README.md
@@ -84,9 +85,11 @@ files:
 - lib/i18n_proofreading/engine.rb
 - lib/i18n_proofreading/marking.rb
 - lib/i18n_proofreading/middleware.rb
+- lib/i18n_proofreading/seeds.rb
 - lib/i18n_proofreading/version.rb
 - lib/i18n_proofreading/widget.js
 - lib/i18n_proofreading/widget.rb
+- lib/tasks/i18n_proofreading_tasks.rake
 homepage: https://github.com/yshmarov/i18n_proofreading
 licenses:
 - MIT