i18n_feedback 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db55035ed25835495f5e4840e9b3e6663a7e745d52600803207e8e38b7f92dcf
+  data.tar.gz: 82cd102f8766cbab2de69c3c69fe56b6fefd8e27efb4f1e897b2556e9ef76510
+SHA512:
+  metadata.gz: 886de0912affd3a3d0e9ed7a20bca10605b6d2da21cb8446028049e0568cefe74ea2c57ee28f083cb29010220eabb3790cd0eec0e0af478ded46f45761a66ef2
+  data.tar.gz: 94e65e65440bf08316bf2b55eacdc8af421dfad8072ac62b1172b93bb8b93ed4974f3b31d2051ba11bb9c4e708299a7a97a4a7bfa60d0fe4606312a888439844

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [Unreleased]
+
+## [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_feedback=true` / `false`, remembered in a cookie) so suggest mode can
+  be triggered from a host-provided link instead.
+- `I18nFeedback::Suggestion` model and mountable engine endpoints for listing and
+  creating suggestions.
+- `i18n_feedback: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,172 @@
+# i18n_feedback
+
+In-context translation proofreading for Rails.
+
+`i18n_feedback` 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.
+
+- **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_feedback_suggestions` table for you to review and apply.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+
+## Installation
+
+Add the gem (from source until it is published on RubyGems):
+
+```ruby
+# Gemfile
+gem "i18n_feedback", github: "yshmarov/i18n-feedback"
+```
+
+```bash
+bundle install
+bin/rails generate i18n_feedback:install
+bin/rails db:migrate
+```
+
+The generator:
+
+- writes `config/initializers/i18n_feedback.rb`,
+- creates the `i18n_feedback_suggestions` migration,
+- mounts the engine in `config/routes.rb`:
+
+  ```ruby
+  mount I18nFeedback::Engine => "/i18n_feedback"
+  ```
+
+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_feedback.rb
+I18nFeedback.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 }
+
+  # 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_feedback"
+
+  # Keep in sync with the `mount` in config/routes.rb.
+  config.mount_path = "/i18n_feedback"
+end
+```
+
+### Toggling suggest mode from your own link
+
+Prefer a menu item over the floating pill? Hide the pill and link to the toggle
+parameter from anywhere in your UI:
+
+```ruby
+config.show_pill = false
+```
+
+```erb
+<%= link_to "Proofread translations", "?i18n_feedback=true" %>
+```
+
+`?i18n_feedback=true` turns suggest mode on and `?i18n_feedback=false` turns it
+off. The choice is remembered in a cookie, so the rest of the app stays in
+suggest mode without the parameter; `Esc` also exits.
+
+### 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_feedback) }
+```
+
+### Placing the widget yourself
+
+Set `config.auto_inject = false` and drop the helper at the end of your layout:
+
+```erb
+<%= i18n_feedback_tag %>
+```
+
+It renders nothing unless the tool is available for the request.
+
+## Reviewing suggestions
+
+Suggestions are ordinary records:
+
+```ruby
+I18nFeedback::Suggestion.order(created_at: :desc).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`, and optional `author_id` / `author_label`.
+
+## 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.
+
+## 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,11 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake' if File.exist?(APP_RAKEFILE)
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/assets/i18n_feedback/widget.js

@@ -0,0 +1,379 @@
+/*
+ * i18n_feedback widget — self-contained, no framework, no build step.
+ *
+ * Reads window.__i18nFeedback = { endpoint, locale, active }.
+ *
+ * A floating pill toggles "suggest mode", which is server state: the pill sets or
+ * clears the i18n_feedback cookie and reloads, so the backend only prints the
+ * "…text… ⟦some.key.path⟧" markers while proofreading. The markers are never shown
+ * to the user — on load the widget strips each ⟦key⟧ token out of the DOM and
+ * stashes the key on its element. A click on any such element opens a popover to
+ * suggest a wording; navigation is frozen while the popover is open. Esc, or the
+ * pill, exits.
+ */
+(function () {
+  "use strict";
+
+  var config = window.__i18nFeedback;
+  if (!config || window.__i18nFeedbackLoaded) return;
+  window.__i18nFeedbackLoaded = true;
+
+  var LEFT = "⟦"; // ⟦
+  var RIGHT = "⟧"; // ⟧
+  var TOKEN = new RegExp(LEFT + "([^" + RIGHT + "]+)" + RIGHT);
+  var TOKENS = new RegExp("\\s*" + LEFT + "[^" + RIGHT + "]+" + RIGHT, "g");
+  var COOKIE = "i18n_feedback";
+  var MARKED_ATTRS = ["placeholder", "title", "aria-label", "value"];
+  var Z = 2147483000;
+
+  var overlay = null;
+  var proposedInput = null;
+  var commentInput = null;
+  var errorNode = null;
+  var saveButton = null;
+  var priorNode = null;
+
+  function ready(fn) {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", fn);
+    } else {
+      fn();
+    }
+  }
+
+  ready(function () {
+    injectStyles();
+    if (config.showPill !== false) buildPill();
+    document.addEventListener("keydown", handleKeydown);
+
+    if (config.active) {
+      document.documentElement.classList.add("i18nf-active");
+      document.addEventListener("click", handleClick, true);
+      document.addEventListener("turbo:load", strip);
+      document.addEventListener("turbo:frame-load", strip);
+      strip();
+    }
+  });
+
+  // --- suggest-mode toggle --------------------------------------------------
+
+  function toggle() {
+    if (config.active) {
+      document.cookie = COOKIE + "=; path=/; max-age=0";
+    } else {
+      document.cookie = COOKIE + "=1; path=/";
+    }
+    window.location.reload();
+  }
+
+  // --- marker stripping -----------------------------------------------------
+
+  function strip() {
+    var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+      acceptNode: function (node) {
+        var tag = node.parentElement && node.parentElement.tagName;
+        if (tag === "SCRIPT" || tag === "STYLE") return NodeFilter.FILTER_REJECT;
+        return TOKEN.test(node.nodeValue) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
+      },
+    });
+
+    var nodes = [];
+    while (walker.nextNode()) nodes.push(walker.currentNode);
+
+    nodes.forEach(function (node) {
+      var match = node.nodeValue.match(TOKEN);
+      if (!match) return;
+      var key = match[1];
+      node.nodeValue = node.nodeValue.replace(TOKENS, "");
+      var element = node.parentElement;
+      if (element) {
+        element.dataset.i18nKey = key;
+        element.dataset.i18nValue = node.nodeValue.trim();
+      }
+    });
+
+    MARKED_ATTRS.forEach(function (attr) {
+      var selector = "[" + attr + '*="' + LEFT + '"]';
+      document.querySelectorAll(selector).forEach(function (element) {
+        element.setAttribute(attr, element.getAttribute(attr).replace(TOKENS, ""));
+      });
+    });
+  }
+
+  // --- interaction ----------------------------------------------------------
+
+  function handleClick(event) {
+    if (overlay && overlay.contains(event.target)) return;
+    if (event.target.closest && event.target.closest(".i18nf-pill")) return;
+
+    // Freeze navigation so a stray click can't leave the page mid-proofread.
+    event.preventDefault();
+    event.stopPropagation();
+
+    var element = event.target.closest && event.target.closest("[data-i18n-key]");
+    if (element) open(element.dataset.i18nKey, element.dataset.i18nValue || "");
+  }
+
+  function handleKeydown(event) {
+    if (event.key !== "Escape") return;
+    if (overlay) close();
+    else if (config.active) toggle();
+  }
+
+  // --- pill -----------------------------------------------------------------
+
+  function buildPill() {
+    var pill = document.createElement("button");
+    pill.type = "button";
+    pill.className = "i18nf-pill" + (config.active ? " i18nf-pill-on" : "");
+    pill.textContent = config.active ? "✓ Suggesting — tap to exit (Esc)" : "✎ " + labelText();
+    pill.addEventListener("click", toggle);
+    document.body.appendChild(pill);
+  }
+
+  function labelText() {
+    return (config.pillLabel || "Suggest edits");
+  }
+
+  // --- popover --------------------------------------------------------------
+
+  function open(key, currentValue) {
+    close();
+
+    overlay = el("div", "i18nf-overlay");
+    overlay.addEventListener("click", function (event) {
+      if (event.target === overlay) close();
+    });
+
+    var panel = el("div", "i18nf-panel");
+    panel.appendChild(heading(key));
+
+    priorNode = el("div");
+    panel.appendChild(priorNode);
+
+    panel.appendChild(field("Current text", readonly(currentValue)));
+
+    proposedInput = textarea(currentValue);
+    panel.appendChild(field("Suggested text", proposedInput));
+
+    commentInput = input("Optional note for the developer");
+    panel.appendChild(field("Comment", commentInput));
+
+    errorNode = el("p", "i18nf-error");
+    errorNode.style.display = "none";
+    panel.appendChild(errorNode);
+
+    panel.appendChild(actions(key, currentValue));
+
+    overlay.appendChild(panel);
+    document.body.appendChild(overlay);
+    proposedInput.focus();
+    loadPrior(key);
+  }
+
+  function close() {
+    if (overlay) {
+      overlay.remove();
+      overlay = null;
+    }
+  }
+
+  function loadPrior(key) {
+    var params = new URLSearchParams({ key: key, locale: config.locale });
+    fetch(config.endpoint + "?" + params.toString(), { headers: { Accept: "application/json" } })
+      .then(function (response) {
+        return response.ok ? response.json() : [];
+      })
+      .then(function (items) {
+        if (items && items.length) renderPrior(items);
+      })
+      .catch(function () {
+        // Best-effort context; ignore fetch/parse errors.
+      });
+  }
+
+  function renderPrior(items) {
+    if (!priorNode) return;
+
+    var box = el("div", "i18nf-prior");
+    var title = el("p", "i18nf-prior-title");
+    title.textContent = "Already suggested (pending)";
+    box.appendChild(title);
+
+    var list = el("ul", "i18nf-prior-list");
+    items.forEach(function (item) {
+      var row = document.createElement("li");
+      var who = item.author_label ? " — " + item.author_label : "";
+      row.textContent = "“" + item.proposed_value + "”" + who;
+      list.appendChild(row);
+    });
+    box.appendChild(list);
+
+    priorNode.replaceWith(box);
+    priorNode = box;
+  }
+
+  function actions(key, currentValue) {
+    var wrapper = el("div", "i18nf-actions");
+
+    var cancel = el("button", "i18nf-btn i18nf-btn-ghost");
+    cancel.type = "button";
+    cancel.textContent = "Cancel";
+    cancel.addEventListener("click", close);
+
+    saveButton = el("button", "i18nf-btn i18nf-btn-primary");
+    saveButton.type = "button";
+    saveButton.textContent = "Send suggestion";
+    saveButton.addEventListener("click", function () {
+      submit(key, currentValue);
+    });
+
+    wrapper.appendChild(cancel);
+    wrapper.appendChild(saveButton);
+    return wrapper;
+  }
+
+  function submit(key, currentValue) {
+    var proposed = proposedInput.value.trim();
+    if (!proposed) {
+      showError("Please enter a suggestion.");
+      return;
+    }
+
+    saveButton.disabled = true;
+
+    fetch(config.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-CSRF-Token": csrfToken(),
+      },
+      body: JSON.stringify({
+        suggestion: {
+          translation_key: key,
+          locale: config.locale,
+          old_value: currentValue,
+          proposed_value: proposed,
+          comment: commentInput.value.trim(),
+          page_url: window.location.href,
+        },
+      }),
+    })
+      .then(function (response) {
+        if (response.ok) {
+          close();
+        } else {
+          saveButton.disabled = false;
+          showError("Could not save the suggestion.");
+        }
+      })
+      .catch(function () {
+        saveButton.disabled = false;
+        showError("Could not save the suggestion.");
+      });
+  }
+
+  function showError(message) {
+    errorNode.textContent = message;
+    errorNode.style.display = "";
+  }
+
+  // --- small DOM builders ---------------------------------------------------
+
+  function heading(key) {
+    var wrapper = el("div", "i18nf-heading");
+    var title = el("p", "i18nf-title");
+    title.textContent = "Suggest a translation fix";
+    var code = el("code", "i18nf-key");
+    code.textContent = key;
+    wrapper.appendChild(title);
+    wrapper.appendChild(code);
+    return wrapper;
+  }
+
+  function field(label, control) {
+    var wrapper = el("label", "i18nf-field");
+    var text = el("span", "i18nf-label");
+    text.textContent = label;
+    wrapper.appendChild(text);
+    wrapper.appendChild(control);
+    return wrapper;
+  }
+
+  function readonly(value) {
+    var node = el("p", "i18nf-readonly");
+    node.textContent = value;
+    return node;
+  }
+
+  function textarea(value) {
+    var node = el("textarea", "i18nf-input");
+    node.rows = 3;
+    node.value = value;
+    return node;
+  }
+
+  function input(placeholder) {
+    var node = el("input", "i18nf-input");
+    node.type = "text";
+    node.placeholder = placeholder;
+    return node;
+  }
+
+  function el(tag, className) {
+    var node = document.createElement(tag);
+    if (className) node.className = className;
+    return node;
+  }
+
+  function csrfToken() {
+    var meta = document.querySelector('meta[name="csrf-token"]');
+    return meta ? meta.content : "";
+  }
+
+  // --- styles ---------------------------------------------------------------
+
+  function injectStyles() {
+    if (document.getElementById("i18nf-styles")) return;
+    var style = document.createElement("style");
+    style.id = "i18nf-styles";
+    style.textContent = [
+      // Only the strings that actually resolve to a key are editable, so only
+      // those are highlighted. `outline` (not `border`) avoids any layout shift.
+      ".i18nf-active [data-i18n-key] { cursor: copy; outline: 1px dashed rgba(37, 99, 235, 0.5); outline-offset: 2px; }",
+      ".i18nf-active [data-i18n-key]:hover { outline: 2px dashed #2563eb; outline-offset: 2px; background: rgba(37, 99, 235, 0.08); }",
+      ".i18nf-pill { position: fixed; bottom: 16px; left: 16px; z-index: " + (Z + 1) + ";",
+      "  font: 13px/1.2 system-ui, sans-serif; padding: 9px 14px; border-radius: 999px;",
+      "  border: 1px solid rgba(0,0,0,.15); background: #fff; color: #111; cursor: pointer;",
+      "  box-shadow: 0 4px 14px rgba(0,0,0,.18); }",
+      ".i18nf-pill-on { background: #2563eb; color: #fff; border-color: #2563eb; }",
+      ".i18nf-overlay { position: fixed; inset: 0; z-index: " + (Z + 2) + "; display: flex;",
+      "  align-items: center; justify-content: center; padding: 16px;",
+      "  background: rgba(0,0,0,.45); cursor: default; }",
+      ".i18nf-panel { width: 28rem; max-width: 100%; max-height: 90vh; overflow: auto;",
+      "  background: #fff; color: #111; border-radius: 12px; padding: 20px;",
+      "  box-shadow: 0 20px 60px rgba(0,0,0,.35); font: 14px/1.5 system-ui, sans-serif; }",
+      ".i18nf-panel > * + * { margin-top: 14px; }",
+      ".i18nf-title { font-weight: 700; font-size: 15px; margin: 0; }",
+      ".i18nf-key { display: block; margin-top: 2px; font-size: 12px; color: #666;",
+      "  word-break: break-all; font-family: ui-monospace, monospace; }",
+      ".i18nf-field { display: block; }",
+      ".i18nf-label { display: block; margin-bottom: 4px; font-size: 12px; color: #666; }",
+      ".i18nf-readonly { margin: 0; padding: 8px 10px; background: #f4f4f5; border-radius: 8px; }",
+      ".i18nf-input { display: block; width: 100%; box-sizing: border-box; padding: 8px 10px;",
+      "  border: 1px solid #d4d4d8; border-radius: 8px; font: inherit; }",
+      ".i18nf-prior { padding: 10px 12px; background: #f4f4f5; border-radius: 8px; font-size: 13px; }",
+      ".i18nf-prior-title { margin: 0 0 4px; font-weight: 600; color: #555; }",
+      ".i18nf-prior-list { margin: 0; padding-left: 18px; }",
+      ".i18nf-error { margin: 0; color: #dc2626; font-size: 13px; }",
+      ".i18nf-actions { display: flex; justify-content: flex-end; gap: 8px; }",
+      ".i18nf-btn { padding: 8px 14px; border-radius: 8px; border: 1px solid transparent;",
+      "  font: inherit; cursor: pointer; }",
+      ".i18nf-btn-ghost { background: transparent; color: #111; }",
+      ".i18nf-btn-primary { background: #2563eb; color: #fff; }",
+      ".i18nf-btn[disabled] { opacity: .6; cursor: default; }",
+    ].join("\n");
+    document.head.appendChild(style);
+  }
+})();

data/app/controllers/i18n_feedback/application_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    before_action :require_available
+
+    private
+
+    # Server-side gate. 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 I18nFeedback.available?(request)
+    end
+
+    def current_author
+      return @current_author if defined?(@current_author)
+
+      @current_author = I18nFeedback.config.current_user.call(request)
+    end
+  end
+end

data/app/controllers/i18n_feedback/suggestions_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  class SuggestionsController < ApplicationController
+    # Pending suggestions for one key/locale, shown as read-only context when the
+    # proofreader reopens the popover for a string someone already flagged.
+    def index
+      suggestions = Suggestion
+                    .where(translation_key: params[:key], locale: params[:locale])
+                    .order(id: :desc)
+                    .limit(20)
+
+      render json: suggestions.map { |suggestion| suggestion_json(suggestion) }
+    end
+
+    def create
+      suggestion = Suggestion.new(suggestion_params)
+      attribute_author(suggestion)
+
+      if suggestion.save
+        head :created
+      else
+        render json: { errors: suggestion.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def attribute_author(suggestion)
+      author = current_author
+      return unless author
+
+      suggestion.author_id = author.id.to_s if author.respond_to?(:id)
+      suggestion.author_label = I18nFeedback.config.author_label.call(author)
+    end
+
+    def suggestion_json(suggestion)
+      {
+        proposed_value: suggestion.proposed_value,
+        author_label: suggestion.author_label,
+        created_at: suggestion.created_at.iso8601
+      }
+    end
+
+    def suggestion_params
+      params
+        .require(:suggestion)
+        .permit(:translation_key, :locale, :old_value, :proposed_value, :comment, :page_url)
+    end
+  end
+end

data/app/helpers/i18n_feedback/tag_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  # Lets a host place the widget explicitly (`<%= i18n_feedback_tag %>` at the end
+  # of a layout) instead of relying on auto-injection. Renders nothing unless the
+  # tool is available for the current request.
+  module TagHelper
+    def i18n_feedback_tag
+      return ''.html_safe unless I18nFeedback.available?(request)
+
+      Widget.snippet(
+        endpoint: I18nFeedback.config.suggestions_endpoint,
+        locale: I18n.locale,
+        active: I18nFeedback::Marking.enabled?
+      ).html_safe
+    end
+  end
+end

data/app/models/i18n_feedback/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/i18n_feedback/suggestion.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  # A proposed wording for one translation key in one locale. Author attribution
+  # is optional and stored as loose fields (no foreign key to the host's user
+  # table) so the model is portable across apps with different user models.
+  class Suggestion < ApplicationRecord
+    validates :translation_key, presence: true
+    validates :proposed_value, presence: true
+    validates :locale,
+              presence: true,
+              inclusion: { in: ->(_) { I18nFeedback.config.available_locales.call.map(&:to_s) } }
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+I18nFeedback::Engine.routes.draw do
+  resources :suggestions, only: %i[index create]
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module I18nFeedback
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs i18n_feedback: config initializer, migration, and engine mount.'
+
+      def create_initializer
+        copy_file 'initializer.rb', 'config/initializers/i18n_feedback.rb'
+      end
+
+      def create_suggestions_migration
+        migration_template 'create_i18n_feedback_suggestions.rb.tt',
+                           'db/migrate/create_i18n_feedback_suggestions.rb'
+      end
+
+      def mount_engine
+        route %(mount I18nFeedback::Engine => "/i18n_feedback")
+      end
+
+      def post_install
+        say "\ni18n_feedback installed. Run `rails db:migrate`, then boot in development", :green
+        say "and look for the “Suggest edits” pill in the bottom-left corner.\n"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/i18n_feedback/install/templates/create_i18n_feedback_suggestions.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateI18nFeedbackSuggestions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :i18n_feedback_suggestions do |t|
+      t.string :translation_key, null: false
+      t.string :locale, null: false
+      t.text :old_value
+      t.text :proposed_value, null: false
+      t.text :comment
+      t.string :page_url
+      t.string :author_id
+      t.string :author_label
+
+      t.timestamps
+    end
+
+    add_index :i18n_feedback_suggestions, %i[translation_key locale]
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+I18nFeedback.configure do |config|
+  # Environments the tool is active in. It is never active anywhere else.
+  config.enabled_environments = %w[development staging]
+
+  # Per-request gate on top of the environment check. Return false to hide the
+  # tool. Receives the Rack::Request — plug in an admin check, a feature flag, an
+  # IP allowlist, etc.
+  #
+  # config.enabled = ->(request) { true }
+
+  # 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
+  # user however your app does — session, Warden, a token, etc.
+  #
+  # config.current_user = ->(request) { nil }
+
+  # How to label the author in the "already suggested" list.
+  #
+  # config.author_label = ->(user) { user.try(:email) }
+
+  # The widget is injected into HTML responses automatically. Set this to false to
+  # place it yourself with `<%= i18n_feedback_tag %>` at the end of your layout.
+  #
+  # config.auto_inject = true
+
+  # Show the floating "Suggest edits" pill. Set false to hide it and toggle
+  # suggest mode from your own link instead, e.g.
+  # `<%= link_to "Proofread", "?i18n_feedback=true" %>`. "?i18n_feedback=false"
+  # exits; the choice is remembered in a cookie.
+  #
+  # config.show_pill = true
+  # config.toggle_param = "i18n_feedback"
+
+  # Keep this in sync with the `mount` line in config/routes.rb.
+  #
+  # config.mount_path = "/i18n_feedback"
+end

data/lib/i18n_feedback/configuration.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  # Host-tunable settings. Everything has a safe default, so a fresh install works
+  # with zero configuration in development; the hooks below let an app decide who
+  # sees the tool and how suggestions are attributed.
+  class Configuration
+    # Environments the tool is active in. It is never active anywhere else, so a
+    # production deploy can't accidentally expose the key markers or the endpoint.
+    attr_accessor :enabled_environments
+
+    # Per-request gate, on top of the environment check. Return false to hide the
+    # tool for this request. Receives the Rack::Request. Plug in an admin check, a
+    # feature flag, an allowlist, etc.
+    attr_accessor :enabled
+
+    # Resolve the current user for attribution (optional). Return an object
+    # responding to #id, or nil. Receives the Rack::Request.
+    attr_accessor :current_user
+
+    # Turn a resolved user into a short label shown in the "already suggested"
+    # list. Receives whatever #current_user returned.
+    attr_accessor :author_label
+
+    # The locales a suggestion may target. Used to validate submissions.
+    attr_accessor :available_locales
+
+    # Inject the widget into HTML responses automatically. Set false to place it
+    # yourself with `<%= i18n_feedback_tag %>` in your layout.
+    attr_accessor :auto_inject
+
+    # Where the engine is mounted. The widget posts suggestions to
+    # "#{mount_path}/suggestions", so keep this in sync with the `mount` line in
+    # your routes.
+    attr_accessor :mount_path
+
+    # Show the floating toggle pill. Set false to hide it and drive suggest mode
+    # from your own link instead (see #toggle_param).
+    attr_accessor :show_pill
+
+    # Text on the floating toggle pill.
+    attr_accessor :pill_label
+
+    # The query-string parameter that turns suggest mode on/off, so a host can
+    # link to it from anywhere: "?i18n_feedback=true" enables it, "false" exits.
+    # The choice is remembered in a cookie, so the rest of the app stays in
+    # suggest mode without the parameter.
+    attr_accessor :toggle_param
+
+    def initialize
+      @enabled_environments = %w[development staging]
+      @enabled = ->(_request) { true }
+      @current_user = ->(_request) {}
+      @author_label = ->(user) { user.respond_to?(:email) ? user.email : user&.to_s }
+      @available_locales = -> { I18n.available_locales.map(&:to_s) }
+      @auto_inject = true
+      @mount_path = '/i18n_feedback'
+      @show_pill = true
+      @pill_label = 'Suggest edits'
+      @toggle_param = 'i18n_feedback'
+    end
+
+    def environment_enabled?
+      enabled_environments.map(&:to_s).include?(Rails.env.to_s)
+    end
+
+    def suggestions_endpoint
+      "#{mount_path.chomp('/')}/suggestions"
+    end
+  end
+end

data/lib/i18n_feedback/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  class Engine < ::Rails::Engine
+    isolate_namespace I18nFeedback
+
+    initializer 'i18n_feedback.middleware' do |app|
+      app.middleware.use I18nFeedback::Middleware
+    end
+
+    # Prepend the key-marking backend once the app (and its I18n backend) is up,
+    # and only in an enabled environment, so production never carries the patch.
+    config.after_initialize do
+      if I18nFeedback.config.environment_enabled? &&
+         !I18n.backend.class.include?(I18nFeedback::Marking::Backend)
+        I18n.backend.class.prepend(I18nFeedback::Marking::Backend)
+      end
+    end
+
+    initializer 'i18n_feedback.helper' do
+      ActiveSupport.on_load(:action_view) do
+        include I18nFeedback::TagHelper
+      end
+    end
+  end
+end

data/lib/i18n_feedback/marking.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module I18nFeedback
+  # Appends a "⟦namespace.key⟧" marker to each translated string so the widget can
+  # map rendered text back to its i18n key. The marker is never shown to the user:
+  # the widget strips every token out of the DOM on load and stashes the key on the
+  # element. Marking is a per-request, per-thread toggle (see Middleware), so pages
+  # stay clean unless a proofreader has switched the tool on.
+  module Marking
+    LEFT = '⟦'
+    RIGHT = '⟧'
+
+    # Skip format/lookup namespaces — marking these would corrupt number, date,
+    # and currency formatting and interpolation strings.
+    SKIP = /(\A|\.)(number|date|time|datetime|support)(\.|\z)|formats?\z/
+
+    class << self
+      def enabled?
+        Thread.current[:i18n_feedback_marking] || false
+      end
+
+      def enabled=(value)
+        Thread.current[:i18n_feedback_marking] = value
+      end
+    end
+
+    # Prepended onto the active I18n backend class.
+    module Backend
+      def translate(locale, key, options = {})
+        result = super
+        return result unless Marking.enabled? && result.is_a?(String)
+
+        full = [*options[:scope], key].join('.')
+        return result if full.match?(SKIP)
+
+        # `super` returns a plain String even for _html keys (ActionView marks the
+        # helper's output safe after the backend returns), so the marker lands
+        # inside that buffer without changing any html_safe status.
+        "#{result} #{LEFT}#{full}#{RIGHT}"
+      end
+    end
+  end
+end

data/lib/i18n_feedback/middleware.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module I18nFeedback
+  # Runs on every request to (1) flip key-marking on for the duration of the
+  # request when a proofreader has the tool switched on, and (2) inject the widget
+  # into HTML responses so the host needs no layout changes. Both are strictly
+  # gated by I18nFeedback.available?, so nothing happens in a disabled environment.
+  class Middleware
+    COOKIE = 'i18n_feedback'
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      available = I18nFeedback.available?(request)
+
+      # A "?i18n_feedback=true|false" in the URL is a command: it overrides the
+      # cookie for this request and is remembered so the rest of the app stays in
+      # (or out of) suggest mode without the parameter.
+      override = available ? toggle_override(request) : nil
+      marking = available && (override.nil? ? cookie_on?(request) : override)
+      Marking.enabled = marking
+
+      status, headers, body = @app.call(env)
+
+      headers = persist_choice(headers, override) if available && !override.nil?
+
+      if available && I18nFeedback.config.auto_inject && html?(headers) && !request.xhr?
+        status, headers, body = inject(status, headers, body, marking)
+      end
+
+      [status, headers, body]
+    ensure
+      Marking.enabled = false
+    end
+
+    private
+
+    def cookie_on?(request)
+      !request.cookies[COOKIE].to_s.empty?
+    end
+
+    def toggle_override(request)
+      param = I18nFeedback.config.toggle_param
+      return nil unless request.params.key?(param)
+
+      %w[1 true on yes].include?(request.params[param].to_s.strip.downcase)
+    end
+
+    def persist_choice(headers, desired)
+      headers = headers.dup
+      cookie = if desired
+                 "#{COOKIE}=1; path=/; SameSite=Lax"
+               else
+                 "#{COOKIE}=; path=/; max-age=0; SameSite=Lax"
+               end
+      key = header_key(headers, 'set-cookie') || 'set-cookie'
+      existing = headers[key]
+      headers[key] = case existing
+                     when nil then cookie
+                     when Array then existing + [cookie]
+                     else "#{existing}\n#{cookie}"
+                     end
+      headers
+    end
+
+    def header_key(headers, name)
+      headers.key?(name) ? name : headers.keys.find { |k| k.to_s.casecmp?(name) }
+    end
+
+    def html?(headers)
+      content_type(headers).to_s.include?('text/html')
+    end
+
+    def content_type(headers)
+      headers['Content-Type'] || headers['content-type']
+    end
+
+    def inject(status, headers, body, marking)
+      html = +''
+      body.each { |part| html << part.to_s }
+      body.close if body.respond_to?(:close)
+
+      snippet = Widget.snippet(
+        endpoint: I18nFeedback.config.suggestions_endpoint,
+        locale: I18n.locale,
+        active: marking
+      )
+      html = html.include?('</body>') ? html.sub('</body>', "#{snippet}</body>") : html + snippet
+
+      headers = headers.dup
+      headers['Content-Length'] = html.bytesize.to_s if headers.key?('Content-Length') || headers.key?('content-length')
+
+      [status, headers, [html]]
+    end
+  end
+end

data/lib/i18n_feedback/version.rb

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

data/lib/i18n_feedback/widget.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module I18nFeedback
+  # Serves the self-contained browser widget. The JavaScript is plain ES (no
+  # framework, no build step) and styles itself inline, so it drops into any Rails
+  # app regardless of its CSS or JS setup. It is inlined into the page rather than
+  # served as a separate asset to avoid any dependency on the host's asset
+  # pipeline.
+  module Widget
+    SOURCE = File.expand_path('../../app/assets/i18n_feedback/widget.js', __dir__)
+
+    class << self
+      def javascript
+        @javascript ||= File.read(SOURCE)
+      end
+
+      # The two <script> tags to place before </body>: one carrying the runtime
+      # config, one carrying the widget itself.
+      def snippet(endpoint:, locale:, active:)
+        config = {
+          endpoint: endpoint,
+          locale: locale.to_s,
+          active: active ? true : false,
+          showPill: I18nFeedback.config.show_pill ? true : false,
+          pillLabel: I18nFeedback.config.pill_label
+        }
+
+        %(<script data-i18n-feedback>window.__i18nFeedback=#{config.to_json};</script>) +
+          %(<script data-i18n-feedback-widget>#{javascript}</script>)
+      end
+    end
+  end
+end

data/lib/i18n_feedback.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'i18n_feedback/version'
+require 'i18n_feedback/configuration'
+require 'i18n_feedback/marking'
+require 'i18n_feedback/widget'
+require 'i18n_feedback/middleware'
+require 'i18n_feedback/engine'
+
+# In-context translation proofreading for Rails. Renders each i18n key alongside
+# its text in the chosen environments, lets a proofreader click any string and
+# suggest a better wording, and stores the suggestions for a developer to apply.
+module I18nFeedback
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Is the tool available for this request? True only in an enabled environment
+    # and when the host's `enabled` predicate passes. Checked on the server for
+    # every marker, endpoint, and injection, so the client can never turn it on.
+    def available?(request)
+      config.environment_enabled? && !!config.enabled.call(request)
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: i18n_feedback
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yaroslav Shmarov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: |
+  A mountable Rails engine that renders each translation alongside its i18n key
+  in development and staging, lets reviewers click any string in the running app
+  and propose a better wording, and stores those suggestions for a developer to
+  apply. Framework-agnostic: no CSS or JS framework required.
+email:
+- yaroslav.shmarov@clickfunnels.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/i18n_feedback/widget.js
+- app/controllers/i18n_feedback/application_controller.rb
+- app/controllers/i18n_feedback/suggestions_controller.rb
+- app/helpers/i18n_feedback/tag_helper.rb
+- app/models/i18n_feedback/application_record.rb
+- app/models/i18n_feedback/suggestion.rb
+- config/routes.rb
+- lib/generators/i18n_feedback/install/install_generator.rb
+- lib/generators/i18n_feedback/install/templates/create_i18n_feedback_suggestions.rb.tt
+- lib/generators/i18n_feedback/install/templates/initializer.rb
+- lib/i18n_feedback.rb
+- lib/i18n_feedback/configuration.rb
+- lib/i18n_feedback/engine.rb
+- lib/i18n_feedback/marking.rb
+- lib/i18n_feedback/middleware.rb
+- lib/i18n_feedback/version.rb
+- lib/i18n_feedback/widget.rb
+homepage: https://github.com/yshmarov/i18n-feedback
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/yshmarov/i18n-feedback
+  changelog_uri: https://github.com/yshmarov/i18n-feedback/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: 'In-context i18n proofreading for Rails: click any translated string and
+  suggest a fix.'
+test_files: []