i18n_proofreading 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 578d960a613d57612657b905fb64b4625dd665e19ef02d90c61493d032058372
+  data.tar.gz: b8653d8cee11804f5765391a55e8b055d415ccb0681d7def0b144c1987f6410f
+SHA512:
+  metadata.gz: c85beac359797b0eb32321adcce88f0859e4b30943754e9ff4fa106168ccc4891ccf678e31b0f908d80f1b42183a5696ad7371dddd529378df49c11d9d2016f4
+  data.tar.gz: 04e0f42e8a0c1991094fc13b84530cb39876073f1f9e615d6d1c8df2f11e398c867ef78f66f46570bd9e5c51b311f00c2d0df1a180206de533ac25e94a3b0acf

data/CHANGELOG.md

@@ -0,0 +1,214 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.9.0]
+
+- **Renamed the gem `i18n_feedback` → `i18n_proofreading`.** The name now says
+  what it does. This renames everything: the gem, the `I18nProofreading` module,
+  the `i18n_proofreading.*` locale scope, the suggest-mode cookie / toggle
+  parameter (`i18n_proofreading`), the default mount path (`/i18n_proofreading`),
+  and the DB table (`i18n_proofreading_suggestions`).
+
+  **Migrating from `i18n_feedback`:** point your `Gemfile` at `i18n_proofreading`,
+  rename the initializer, and rename the table + any references:
+
+  ```ruby
+  # a migration
+  rename_table :i18n_feedback_suggestions, :i18n_proofreading_suggestions
+  ```
+
+  Then update `I18nFeedback` → `I18nProofreading`, the `config/initializers`
+  file, the `mount` line, any `t("i18n_feedback.*")` you added, and the
+  `?i18n_feedback=` toggle links to their `i18n_proofreading` equivalents.
+
+- **Switched the test suite from RSpec to Minitest** (`test/`, `bin/rails test`
+  / `rake test`). No behavior change; internal only.
+
+## [0.8.2]
+
+- Fix the dashboard's locale filter doing nothing under a strict (nonce-based)
+  Content-Security-Policy: it relied on an inline `onchange` handler, which such
+  a CSP blocks. The filter now has an always-visible **Filter** submit button, so
+  it works with JS off or inline handlers blocked (the `onchange` stays as a
+  nicety where allowed).
+- Give the locale filter a visible **Locale** label.
+
+## [0.8.1]
+
+- Make the dashboard **read-only**. Apply / Reject / Reopen / Delete only ever
+  flipped the stored `status` — they never touched the host's locale files, so
+  offering them implied a capability the gem doesn't have. The buttons and their
+  `update` / `destroy` routes and actions are removed; the dashboard now just
+  lists suggestions for review, and you make the edits in your own locale files.
+  A suggestion's `status` still exists on the model for out-of-band tracking and
+  as groundwork for a future "apply to locale file" feature.
+
+## [0.8.0]
+
+- Add a built-in **triage dashboard**, mounted at the engine root (your
+  `mount_path`, default `/i18n_proofreading`): pending / applied / rejected tabs
+  with counts, a per-locale filter, each suggestion shown current-vs-proposed,
+  and one-click Apply / Reject / Reopen / Delete. Plain server-rendered HTML
+  with its own self-contained styling (light + dark via `prefers-color-scheme`)
+  — no host assets or JS framework required.
+- Every dashboard string renders through Rails I18n under `i18n_proofreading.dashboard.*`
+  and `i18n_proofreading.statuses.*`, with English fallbacks, so a host can translate
+  or reword any of it from its own locale files.
+- Add `config.authorize_admin` — the dashboard's gate, **defaulting to
+  development only** so a fresh install never exposes it in production. It is
+  independent of `enabled` / `enabled_environments`, so a maintainer can triage
+  from production even where the widget is off.
+- The widget's "already suggested" context now loads from
+  `GET {mount_path}/suggestions/context` (was the collection index, now the
+  dashboard). Internal to the gem; the bundled widget was updated in lockstep.
+
+## [0.7.1]
+
+- The `i18n_proofreading.stop` toggle label now reads "Stop suggesting (Esc)" in
+  every language — Esc already exits suggest mode, so the control says so.
+- The widget JavaScript moved from `app/assets/` to `lib/` (it was always
+  inlined server-side, never served as an asset). Rails auto-registers every
+  engine's `app/assets/*` directory with the host's asset pipeline, so
+  Propshaft hosts were ingesting the file into their asset namespace under
+  the bare logical name `widget.js` — colliding with any other gem or host
+  file of the same name — and needlessly digesting a public copy at
+  precompile. The gem is now invisible to Sprockets/Propshaft entirely.
+  No behavior change.
+
+## [0.7.0]
+
+- Reword the `i18n_proofreading.start` toggle label from "Suggest edits" to
+  "Improve translation" (localized in every language) — clearer for a menu/link
+  entry. The floating pill's own label (`pill`) is unchanged.
+- Ship 5 more languages: Bulgarian, Greek, Croatian, Luxembourgish, and
+  Romanian — 25 languages besides English now bundled.
+
+## [0.6.1]
+
+- Shorten the active-pill label from "Suggesting — tap to exit (Esc)" to
+  "Stop suggesting (Esc)" across all bundled languages.
+- Release workflow: skip the flaky post-publish propagation probe
+  (`await-release: false`) so a successful push no longer fails the job.
+
+## [0.6.0]
+
+- Ship `i18n_proofreading.start` / `i18n_proofreading.stop` labels in every bundled
+  language, for hosts that drive suggest mode from their own menu/link instead
+  of the floating pill. Because the `i18n_proofreading.*` scope is exempt from
+  key-marking, these are safe to render with `t(...)` — no plain-literal
+  workaround needed. See the "Toggling suggest mode from your own link" README
+  section for a full HTML example.
+
+## [0.5.0]
+
+- Add a `status` to each suggestion — a string-backed Active Record enum with
+  values `pending`, `applied`, and `rejected` (`I18nProofreading::Suggestion::STATUSES`),
+  `status_`-prefixed (`status_applied?`, `status_applied!`, `Suggestion.status_pending`)
+  plus a `newest_first` scope. New suggestions start `pending`; the popover's
+  "already suggested" context now shows only pending ones, so applied/rejected
+  wordings stop resurfacing.
+
+  **Upgrading an existing install:** add the column with a migration —
+
+  ```ruby
+  add_column :i18n_proofreading_suggestions, :status, :string, null: false, default: "pending"
+  add_index  :i18n_proofreading_suggestions, :status
+  ```
+
+- Harden the public submission endpoint against abuse:
+  - Per-IP rate limiting via Rails' built-in limiter (Rails 7.2+; a no-op on
+    7.1). Default 30 requests / 60s, tunable or disable-able via
+    `config.rate_limit`; returns `429 Too Many Requests`.
+  - Length caps on the stored free-text fields (`proposed_value` / `old_value`
+    5000, `comment` / `page_url` 2000, `translation_key` 500) so a client can't
+    bloat the table with unbounded input.
+
+- Add a `.github/workflows/release.yml` that publishes to RubyGems via trusted
+  publishing (OIDC) when a `v*` tag is pushed — no stored credentials or MFA
+  prompt.
+
+## [0.4.0]
+
+- Add a `config.on_submit` hook, called with each saved suggestion right after
+  it's stored — notify Slack, send an email, open a ticket. Runs inline after
+  save, so keep it fast or hand off to a job.
+
+## [0.3.1]
+
+- Fix the widget showing raw key markers (e.g. `⟦i18n_proofreading.title⟧`) in its own
+  popover while suggest mode was on. The key-marking backend was tagging the
+  tool's own `i18n_proofreading.*` strings; those are not part of the host app's
+  translatable copy, so they're now always skipped — the widget never marks or
+  offers to edit its own UI.
+- Fix the popover not following the page's language under auto-injection. The
+  widget is injected in middleware *after* the controller action, so an
+  `around_action { I18n.with_locale(...) }` had already reset `I18n.locale` back
+  to the default — the popover (and the saved suggestion's `locale`) came out in
+  the wrong language. The locale is now read from the page's rendered
+  `<html lang>` attribute and labels resolve under it explicitly.
+
+## [0.3.0]
+
+- Localize the widget's own UI. Every string in the pill and the suggestion
+  popover now resolves through Rails I18n under the `i18n_proofreading.*` scope and
+  follows the app's current `I18n.locale`, so the tool speaks the same language as
+  the app being proofread. Any key a host hasn't translated falls back to English
+  — so nothing goes blank in a locale you haven't fully covered. Override any
+  string by defining the matching key in your own locale files.
+- Ship translations out of the box for 20 languages in addition to English:
+  Arabic, Bengali, Chinese (Simplified), Dutch, French, German, Hindi, Indonesian,
+  Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Thai, Turkish,
+  Ukrainian, Urdu and Vietnamese.
+- Render the popover right-to-left for RTL locales (Arabic, Urdu, and other RTL
+  scripts), detected from the active locale's language subtag. The i18n key stays
+  left-to-right, since it's a code identifier rather than prose.
+- `config.pill_label` now defaults to `nil`, meaning "use the localized default".
+  Setting it to a string still overrides the pill text as before.
+- The widget now follows the operating system's light/dark/system appearance via
+  `prefers-color-scheme`. The pill and popover render with a dark surface when the
+  reviewer's system is in dark mode, with no configuration required.
+
+## [0.2.2]
+
+- Fix suggest mode desyncing under a nonce-based CSP on Turbo visits. The runtime
+  config now rides in a `<script type="application/json">` block (data, not code)
+  that the widget re-reads on every `turbo:load`, instead of an executable
+  `<script>` the browser refuses to re-run when Turbo re-evaluates it with a stale
+  nonce. Only the widget code carries the CSP nonce now.
+- Treat `?i18n_proofreading=true|false` as a one-shot command: the middleware sets the
+  cookie and redirects (303) to the same URL without the parameter. The cookie is
+  now the single source of truth, so the parameter no longer sticks in the address
+  bar and the pill's reload can turn suggest mode off.
+- Let a host's own toggle link work while suggest mode is active. Suggest mode
+  freezes navigation so a stray click can't leave the page mid-proofread, but that
+  also froze a `?i18n_proofreading=false` link in your own nav — so the only way out
+  was the pill. Links carrying the toggle parameter are now exempt from the freeze.
+
+## [0.2.1]
+
+- Keep the suggest pill and active-mode highlighting working across Turbo Drive
+  navigations. Turbo replaces `<body>` on each visit, which removed the pill; the
+  widget now re-runs its per-page setup on `turbo:load` instead of only on the
+  initial load, so it no longer requires a hard reload.
+
+## [0.2.0]
+
+- Stamp the injected widget scripts with the request's Content-Security-Policy
+  nonce when one is present, so the tool works under a nonce-based CSP (including
+  `strict-dynamic`). No-op for apps without a CSP nonce.
+
+## [0.1.0]
+
+- Initial release.
+- In-context i18n key markers, gated to configured environments and toggled per
+  request by the widget.
+- Self-contained browser widget (no CSS or JS framework required) with a suggest
+  pill and a per-string suggestion popover. The copy cursor and hover outline
+  appear only on the strings that resolve to a key.
+- Optional floating pill (`config.show_pill`) and a URL toggle
+  (`?i18n_proofreading=true` / `false`, remembered in a cookie) so suggest mode can
+  be triggered from a host-provided link instead.
+- `I18nProofreading::Suggestion` model and mountable engine endpoints for listing and
+  creating suggestions.
+- `i18n_proofreading:install` generator (initializer, migration, engine mount).

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaroslav Shmarov
+
+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,325 @@
+# i18n_proofreading
+
+[![Gem Version](https://img.shields.io/gem/v/i18n_proofreading)](https://rubygems.org/gems/i18n_proofreading)
+[![Downloads](https://img.shields.io/gem/dt/i18n_proofreading)](https://rubygems.org/gems/i18n_proofreading)
+[![CI](https://github.com/yshmarov/i18n-proofreading/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/i18n-proofreading/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)
+
+In-context translation proofreading for Rails.
+
+`i18n_proofreading` renders every translated string alongside its i18n key in the
+environments you choose, lets a reviewer click any string in the running app and
+suggest a better wording, and stores those suggestions for a developer to apply.
+It is meant for development and staging, never production.
+
+![Click any string in your running app and suggest a better wording](i18n-proofreading-demo.gif)
+
+<video src="https://github.com/yshmarov/i18n-proofreading/raw/main/i18n-proofreading-demo-640-high.mp4" controls muted playsinline width="640">
+  Your browser can't play this video —
+  <a href="https://github.com/yshmarov/i18n-proofreading/raw/main/i18n-proofreading-demo-640-high.mp4">download it here</a>.
+</video>
+
+- **Zero UI dependencies.** The widget is plain JavaScript and styles itself. No
+  Tailwind, no daisyUI, no Stimulus, no importmap, no build step.
+- **Zero layout changes.** The widget is injected into HTML responses
+  automatically (opt out and place it yourself if you prefer).
+- **Trigger it your way.** Use the built-in floating pill, or hide it and switch
+  suggest mode on from your own link (a nav item, a menu, anywhere).
+- **Pluggable gating and attribution.** You decide which environments and which
+  users see the tool, and how a suggestion is attributed.
+
+## How it works
+
+1. In an enabled environment, the I18n backend appends a hidden `⟦some.key⟧`
+   marker to each translated string. Markers are only emitted while a reviewer
+   has the tool switched on (a cookie), so pages are clean by default.
+2. The browser widget strips every marker out of the DOM on load and remembers
+   which key produced each piece of text.
+3. Clicking a string opens a popover showing the current text, any pending
+   suggestions, and a field to propose a new wording.
+4. Suggestions are `POST`ed to the mounted engine and stored in the
+   `i18n_proofreading_suggestions` table for you to review and apply.
+
+## Turbo
+
+Works with Turbo Drive out of the box. Turbo replaces `<body>` on every visit,
+which would take the pill and the active-mode highlighting with it, so the
+widget registers its document-level listeners once and re-renders on
+`turbo:load`. The pill survives navigation without a full reload.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+
+## Installation
+
+Add the gem:
+
+```ruby
+# Gemfile
+gem "i18n_proofreading"
+```
+
+```bash
+bundle install
+bin/rails generate i18n_proofreading:install
+bin/rails db:migrate
+```
+
+The generator:
+
+- writes `config/initializers/i18n_proofreading.rb`,
+- creates the `i18n_proofreading_suggestions` migration,
+- mounts the engine in `config/routes.rb`:
+
+  ```ruby
+  mount I18nProofreading::Engine => "/i18n_proofreading"
+  ```
+
+Boot the app in development and look for the **“Suggest edits”** pill in the
+bottom-left corner. Click it to turn on suggest mode, then click any text to
+propose a fix. Press `Esc` (or the pill) to exit.
+
+> The widget reads the CSRF token from `<meta name="csrf-token">`, which
+> `csrf_meta_tags` in your layout already provides in a standard Rails app.
+
+## Configuration
+
+Everything is optional; the defaults work out of the box in development.
+
+```ruby
+# config/initializers/i18n_proofreading.rb
+I18nProofreading.configure do |config|
+  # Environments the tool is active in.
+  config.enabled_environments = %w[development staging]
+
+  # Extra per-request gate. Return false to hide the tool. Receives the request.
+  config.enabled = ->(request) { true }
+
+  # Who may open the triage dashboard. Independent of the gates above; defaults
+  # to development only. Wire it to your own admin check to open it elsewhere.
+  config.authorize_admin = ->(request) { Rails.env.development? }
+
+  # Attribute a suggestion to a user (optional). Return an object responding to
+  # #id, or nil. Receives the request.
+  config.current_user = ->(request) { nil }
+
+  # Label shown for the author in the "already suggested" list.
+  config.author_label = ->(user) { user.try(:email) }
+
+  # Inject the widget automatically. Set false to place it yourself.
+  config.auto_inject = true
+
+  # Show the floating "Suggest edits" pill. Set false to drive suggest mode from
+  # your own link instead (see below).
+  config.show_pill = true
+
+  # Query parameter that toggles suggest mode.
+  config.toggle_param = "i18n_proofreading"
+
+  # Keep in sync with the `mount` in config/routes.rb.
+  config.mount_path = "/i18n_proofreading"
+
+  # Per-IP throttle on the submission endpoint, passed to Rails' built-in rate
+  # limiter (Rails 7.2+; ignored on 7.1). Set nil to disable.
+  config.rate_limit = { to: 30, within: 60 }
+end
+```
+
+### Toggling suggest mode from your own link
+
+Prefer a menu item over the floating pill? You can drive suggest mode from any
+link in your own UI — a nav item, a sidebar entry, a footer — and optionally hide
+the pill (the two can also coexist):
+
+```ruby
+config.show_pill = false # optional
+```
+
+A one-way "turn it on" link is just the toggle parameter:
+
+```erb
+<%= link_to t("i18n_proofreading.start"), "?i18n_proofreading=true" %>
+```
+
+For a single control that flips both ways, read the current state from the
+`i18n_proofreading` cookie and point at the opposite state. The gem ships `start`
+and `stop` labels under the `i18n_proofreading.*` scope in every bundled language,
+so a localized toggle needs no keys of your own:
+
+```erb
+<% if I18nProofreading.available?(request) %>
+  <% suggesting = cookies[:i18n_proofreading].present? %>
+  <%= link_to (suggesting ? t("i18n_proofreading.stop") : t("i18n_proofreading.start")),
+              "?#{I18nProofreading.config.toggle_param}=#{!suggesting}" %>
+<% end %>
+```
+
+Good to know:
+
+- `?i18n_proofreading=true` turns suggest mode on, `false` turns it off. The state is
+  stored in the `i18n_proofreading` cookie, and the middleware then redirects to the
+  same URL without the parameter — so it never sticks in the address bar and the
+  cookie stays the single source of truth. `Esc` (or the pill) also exits.
+- These links keep working **while suggest mode is active**. The widget freezes
+  ordinary navigation during proofreading (so a stray click can't leave the page
+  mid-edit), but any link carrying the toggle parameter is exempt — so a "Disable"
+  item in your nav always gets you out.
+- The `i18n_proofreading.*` keys are **safe to run through `I18n.t`** — that scope is
+  exempt from key-marking, so the tool never flags its own controls as editable.
+  Use the bundled `i18n_proofreading.start` / `i18n_proofreading.stop` labels (or your own
+  keys); either way, no plain-literal workaround is needed.
+
+### Gating examples
+
+```ruby
+# Only signed-in staff (however your app resolves that):
+config.enabled = ->(request) { request.env["warden"]&.user&.staff? }
+
+# Behind a feature flag:
+config.enabled = ->(request) { Flipper.enabled?(:i18n_proofreading) }
+```
+
+### Placing the widget yourself
+
+Set `config.auto_inject = false` and drop the helper at the end of your layout:
+
+```erb
+<%= i18n_proofreading_tag %>
+```
+
+It renders nothing unless the tool is available for the request.
+
+### Localizing the widget UI
+
+The pill and the suggestion popover speak the app's language: every string
+resolves through Rails I18n under the `i18n_proofreading.*` scope and follows the
+language the page was rendered in (its `<html lang>`, falling back to
+`I18n.locale`). Translations ship out of the box for English plus 25 more
+languages — Arabic, Bengali, Bulgarian, Chinese (Simplified), Croatian, Dutch,
+French, German, Greek, Hindi, Indonesian, Italian, Japanese, Korean,
+Luxembourgish, Polish, Portuguese, Romanian, Russian, Spanish, Thai, Turkish,
+Ukrainian, Urdu and Vietnamese — so the tool is already localized for most apps.
+RTL locales (Arabic, Urdu, …) render the popover right-to-left automatically.
+
+Any key you haven't translated falls back to English, so a partially translated
+locale never leaves a control blank. To add a language, or reword the bundled
+copy, define the keys in your own locale files (yours win over the gem's):
+
+```yaml
+# config/locales/fr.yml
+fr:
+  i18n_proofreading:
+    pill: "Proposer des corrections"
+    pill_active: "En cours — appuyez pour quitter (Échap)"
+    title: "Proposer une correction de traduction"
+    current_text: "Texte actuel"
+    suggested_text: "Texte proposé"
+    comment: "Commentaire"
+    comment_placeholder: "Note facultative pour le développeur"
+    prior_title: "Déjà proposé (en attente)"
+    cancel: "Annuler"
+    save: "Envoyer la suggestion"
+    error_blank: "Veuillez saisir une suggestion."
+    error_save: "Impossible d'enregistrer la suggestion."
+```
+
+`config.pill_label` still overrides the pill text with a fixed string if you set
+it; leave it `nil` (the default) to use the localized `i18n_proofreading.pill` key.
+
+### Light / dark / system appearance
+
+The widget follows the reviewer's operating-system appearance via
+`prefers-color-scheme` — no configuration needed. The pill and popover render on a
+dark surface when the system is in dark mode and a light surface otherwise; the
+blue accent stays the same in both.
+
+## Reviewing suggestions
+
+### Review dashboard
+
+Mounted at your `mount_path` (default `/i18n_proofreading`), the engine root is a
+built-in **read-only** review board: pending / applied / rejected tabs with
+counts, a per-locale filter, and each suggestion shown as current-vs-proposed
+with its comment and author. It's plain server-rendered HTML with its own
+styling — no host assets or JS framework needed.
+
+It is deliberately read-only. The gem never writes to your locale files, so it
+doesn't pretend to: you review the suggestions here, then make the edits in your
+own `config/locales/*.yml`. (A suggestion's `status` still exists on the model
+for your own tracking — set it from the console — and is the groundwork for a
+future "apply to locale file" feature.)
+
+It has its own gate, `config.authorize_admin`, **defaulting to development
+only** — so a fresh install never exposes it in production. Point it at your own
+admin check to open it elsewhere:
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+The gate is independent of `enabled` / `enabled_environments`: the widget can be
+dev/staging-only while a maintainer still triages from production.
+
+### From the console
+
+Suggestions are also ordinary records:
+
+```ruby
+I18nProofreading::Suggestion.where(status: "pending").newest_first.each do |s|
+  puts "#{s.locale} #{s.translation_key}: #{s.old_value.inspect} -> #{s.proposed_value.inspect}"
+end
+```
+
+Each row stores `translation_key`, `locale`, `old_value`, `proposed_value`,
+`comment`, `page_url`, `status`, and optional `author_id` / `author_label`.
+
+Every suggestion has a `status` — one of `pending`, `applied`, or `rejected`
+(`I18nProofreading::Suggestion::STATUSES`), backed by an Active Record enum. New
+suggestions start `pending`; once you apply a wording to your locale files or
+decide against it, set the status accordingly so the popover stops offering it
+as pending context:
+
+```ruby
+suggestion.status_applied!          # bang setter
+suggestion.status_applied?          # => true
+I18nProofreading::Suggestion.status_pending.newest_first  # scope per status
+```
+
+### Getting notified
+
+To be pinged when a suggestion comes in, set `on_submit`. It's called with the
+saved `Suggestion` right after it's stored — notify Slack, send an email, open a
+ticket. It runs inline in the request, so keep it fast or hand off to a job:
+
+```ruby
+config.on_submit = ->(suggestion) { SuggestionMailer.with(suggestion:).created.deliver_later }
+```
+
+## Security
+
+- The tool is gated **on the server** for every marker, endpoint, and injection.
+  Setting the cookie by hand does nothing outside an enabled environment where
+  `config.enabled` returns true.
+- Format and lookup namespaces (`number.*`, `date.*`, `*_html` formats, etc.) are
+  never marked, so currency and date formatting are unaffected.
+- The injected widget code carries the request's Content-Security-Policy nonce
+  (the same one `ActionDispatch` emits), so it runs under a nonce-based
+  `script-src` policy — including `strict-dynamic` — with no configuration. It is
+  a no-op when the app sets no CSP nonce. The runtime config is shipped as a
+  `<script type="application/json">` block (data, not code), so it needs no nonce
+  and stays correct across Turbo visits.
+
+## Development
+
+```bash
+bin/setup        # or: bundle install
+bundle exec rspec
+```
+
+Tests run against a dummy Rails app under `spec/dummy`.
+
+## License
+
+Released under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+# Defines build/install/release — `rake release` is what the trusted-publishing
+# workflow (.github/workflows/release.yml) runs to push the gem to RubyGems.
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.warning = false
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/i18n_proofreading/application_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module I18nProofreading
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    private
+
+    # 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.
+    def require_available
+      head :forbidden unless I18nProofreading.available?(request)
+    end
+
+    # Gate for the triage dashboard. Independent of #require_available (see
+    # I18nProofreading.admin?). Renders a plain 403 with a hint rather than a bare
+    # head, since a human is usually looking at it.
+    def require_admin
+      return if I18nProofreading.admin?(request)
+
+      render plain: 'Forbidden. Set I18nProofreading.config.authorize_admin to grant access.',
+             status: :forbidden
+    end
+
+    def current_author
+      return @current_author if defined?(@current_author)
+
+      @current_author = I18nProofreading.config.current_user.call(request)
+    end
+  end
+end