i18n_proofreading 0.9.0

data/config/locales/i18n_proofreading.pt.yml

@@ -0,0 +1,16 @@
+pt:
+  i18n_proofreading:
+    pill: "Sugerir edições"
+    start: "Melhorar tradução"
+    stop: "Parar de sugerir (Esc)"
+    pill_active: "Parar de sugerir (Esc)"
+    title: "Sugerir uma correção de tradução"
+    current_text: "Texto atual"
+    suggested_text: "Texto sugerido"
+    comment: "Comentário"
+    comment_placeholder: "Nota opcional para o desenvolvedor"
+    prior_title: "Já sugerido (pendente)"
+    cancel: "Cancelar"
+    save: "Enviar sugestão"
+    error_blank: "Insira uma sugestão."
+    error_save: "Não foi possível salvar a sugestão."

data/config/locales/i18n_proofreading.ro.yml

@@ -0,0 +1,16 @@
+ro:
+  i18n_proofreading:
+    pill: "Sugerează modificări"
+    pill_active: "Oprește sugestiile (Esc)"
+    start: "Îmbunătățește traducerea"
+    stop: "Oprește sugestiile (Esc)"
+    title: "Sugerează o corectură de traducere"
+    current_text: "Text curent"
+    suggested_text: "Text sugerat"
+    comment: "Comentariu"
+    comment_placeholder: "Notă opțională pentru dezvoltator"
+    prior_title: "Deja sugerat (în așteptare)"
+    cancel: "Anulează"
+    save: "Trimite sugestia"
+    error_blank: "Introduceți o sugestie."
+    error_save: "Sugestia nu a putut fi salvată."

data/config/locales/i18n_proofreading.ru.yml

@@ -0,0 +1,16 @@
+ru:
+  i18n_proofreading:
+    pill: "Предложить правки"
+    start: "Улучшить перевод"
+    stop: "Остановить предложения (Esc)"
+    pill_active: "Остановить предложения (Esc)"
+    title: "Предложить исправление перевода"
+    current_text: "Текущий текст"
+    suggested_text: "Предлагаемый текст"
+    comment: "Комментарий"
+    comment_placeholder: "Необязательная заметка для разработчика"
+    prior_title: "Уже предложено (в ожидании)"
+    cancel: "Отмена"
+    save: "Отправить предложение"
+    error_blank: "Введите предложение."
+    error_save: "Не удалось сохранить предложение."

data/config/locales/i18n_proofreading.th.yml

@@ -0,0 +1,16 @@
+th:
+  i18n_proofreading:
+    pill: "แนะนำการแก้ไข"
+    start: "ปรับปรุงคำแปล"
+    stop: "หยุดแนะนำ (Esc)"
+    pill_active: "หยุดแนะนำ (Esc)"
+    title: "แนะนำการแก้ไขคำแปล"
+    current_text: "ข้อความปัจจุบัน"
+    suggested_text: "ข้อความที่แนะนำ"
+    comment: "ความคิดเห็น"
+    comment_placeholder: "หมายเหตุเพิ่มเติมสำหรับนักพัฒนา"
+    prior_title: "แนะนำไปแล้ว (รอดำเนินการ)"
+    cancel: "ยกเลิก"
+    save: "ส่งคำแนะนำ"
+    error_blank: "โปรดป้อนคำแนะนำ"
+    error_save: "ไม่สามารถบันทึกคำแนะนำได้"

data/config/locales/i18n_proofreading.tr.yml

@@ -0,0 +1,16 @@
+tr:
+  i18n_proofreading:
+    pill: "Düzenleme öner"
+    start: "Çeviriyi iyileştir"
+    stop: "Önermeyi durdur (Esc)"
+    pill_active: "Önermeyi durdur (Esc)"
+    title: "Çeviri düzeltmesi öner"
+    current_text: "Mevcut metin"
+    suggested_text: "Önerilen metin"
+    comment: "Yorum"
+    comment_placeholder: "Geliştirici için isteğe bağlı not"
+    prior_title: "Zaten önerildi (beklemede)"
+    cancel: "İptal"
+    save: "Öneriyi gönder"
+    error_blank: "Lütfen bir öneri girin."
+    error_save: "Öneri kaydedilemedi."

data/config/locales/i18n_proofreading.uk.yml

@@ -0,0 +1,16 @@
+uk:
+  i18n_proofreading:
+    pill: "Запропонувати зміни"
+    start: "Покращити переклад"
+    stop: "Зупинити пропозиції (Esc)"
+    pill_active: "Зупинити пропозиції (Esc)"
+    title: "Запропонувати виправлення перекладу"
+    current_text: "Поточний текст"
+    suggested_text: "Запропонований текст"
+    comment: "Коментар"
+    comment_placeholder: "Необов’язкова примітка для розробника"
+    prior_title: "Уже запропоновано (очікує)"
+    cancel: "Скасувати"
+    save: "Надіслати пропозицію"
+    error_blank: "Будь ласка, введіть пропозицію."
+    error_save: "Не вдалося зберегти пропозицію."

data/config/locales/i18n_proofreading.ur.yml

@@ -0,0 +1,16 @@
+ur:
+  i18n_proofreading:
+    pill: "ترامیم تجویز کریں"
+    start: "ترجمہ بہتر بنائیں"
+    stop: "تجویز کرنا بند کریں (Esc)"
+    pill_active: "تجویز کرنا بند کریں (Esc)"
+    title: "ترجمے کی اصلاح تجویز کریں"
+    current_text: "موجودہ متن"
+    suggested_text: "تجویز کردہ متن"
+    comment: "تبصرہ"
+    comment_placeholder: "ڈویلپر کے لیے اختیاری نوٹ"
+    prior_title: "پہلے ہی تجویز کیا جا چکا (زیر التوا)"
+    cancel: "منسوخ کریں"
+    save: "تجویز بھیجیں"
+    error_blank: "براہ کرم ایک تجویز درج کریں۔"
+    error_save: "تجویز محفوظ نہیں ہو سکی۔"

data/config/locales/i18n_proofreading.vi.yml

@@ -0,0 +1,16 @@
+vi:
+  i18n_proofreading:
+    pill: "Đề xuất chỉnh sửa"
+    start: "Cải thiện bản dịch"
+    stop: "Dừng đề xuất (Esc)"
+    pill_active: "Dừng đề xuất (Esc)"
+    title: "Đề xuất sửa bản dịch"
+    current_text: "Văn bản hiện tại"
+    suggested_text: "Văn bản đề xuất"
+    comment: "Nhận xét"
+    comment_placeholder: "Ghi chú tùy chọn cho nhà phát triển"
+    prior_title: "Đã đề xuất (đang chờ)"
+    cancel: "Hủy"
+    save: "Gửi đề xuất"
+    error_blank: "Vui lòng nhập một đề xuất."
+    error_save: "Không thể lưu đề xuất."

data/config/locales/i18n_proofreading.zh-CN.yml

@@ -0,0 +1,16 @@
+zh-CN:
+  i18n_proofreading:
+    pill: "建议修改"
+    start: "改进翻译"
+    stop: "停止建议 (Esc)"
+    pill_active: "停止建议（Esc）"
+    title: "建议翻译修正"
+    current_text: "当前文本"
+    suggested_text: "建议文本"
+    comment: "备注"
+    comment_placeholder: "给开发者的可选备注"
+    prior_title: "已提交建议（待处理）"
+    cancel: "取消"
+    save: "发送建议"
+    error_blank: "请输入建议。"
+    error_save: "无法保存建议。"

data/config/routes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+I18nProofreading::Engine.routes.draw do
+  # index is the read-only admin dashboard; create + the `context` collection
+  # route are the widget's public API (see SuggestionsController). There is
+  # deliberately no update/destroy — the tool never mutates suggestions from the
+  # UI, since it can't write to the host's locale files.
+  resources :suggestions, only: %i[index create] do
+    get :context, on: :collection
+  end
+
+  root to: 'suggestions#index'
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module I18nProofreading
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs i18n_proofreading: config initializer, migration, and engine mount.'
+
+      def create_initializer
+        copy_file 'initializer.rb', 'config/initializers/i18n_proofreading.rb'
+      end
+
+      def create_suggestions_migration
+        migration_template 'create_i18n_proofreading_suggestions.rb.tt',
+                           'db/migrate/create_i18n_proofreading_suggestions.rb'
+      end
+
+      def mount_engine
+        route %(mount I18nProofreading::Engine => "/i18n_proofreading")
+      end
+
+      def post_install
+        say "\ni18n_proofreading 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_proofreading/install/templates/create_i18n_proofreading_suggestions.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateI18nProofreadingSuggestions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :i18n_proofreading_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 :status, null: false, default: 'pending'
+      t.string :author_id
+      t.string :author_label
+
+      t.timestamps
+    end
+
+    add_index :i18n_proofreading_suggestions, %i[translation_key locale]
+    add_index :i18n_proofreading_suggestions, :status
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+I18nProofreading.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 }
+
+  # Who may open the triage dashboard (mounted at your `mount_path`) to review,
+  # apply, and delete suggestions. Independent of the checks above — the widget
+  # is dev/staging-only, but you may want to triage from production. Defaults to
+  # development only; wire it to your own admin check to open it elsewhere.
+  #
+  # config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+
+  # 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_proofreading_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_proofreading=true" %>`. "?i18n_proofreading=false"
+  # exits; the choice is remembered in a cookie.
+  #
+  # config.show_pill = true
+  # config.toggle_param = "i18n_proofreading"
+
+  # Keep this in sync with the `mount` line in config/routes.rb.
+  #
+  # config.mount_path = "/i18n_proofreading"
+
+  # Called with each saved suggestion — notify Slack, send an email, open a
+  # ticket. Runs inline after save, so keep it fast or hand off to a job.
+  #
+  # config.on_submit = ->(suggestion) { SuggestionMailer.with(suggestion:).created.deliver_later }
+
+  # 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

data/lib/i18n_proofreading/configuration.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module I18nProofreading
+  # 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
+
+    # Per-request gate for the triage dashboard (browse suggestions, change their
+    # status, delete). 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
+
+    # 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_proofreading_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. Leave nil to use the localized default
+    # ("Suggest edits", translated via the `i18n_proofreading.pill` I18n key).
+    attr_accessor :pill_label
+
+    # The query-string parameter that turns suggest mode on/off, so a host can
+    # link to it from anywhere: "?i18n_proofreading=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
+
+    # Called with each saved suggestion — notify Slack, send an email, open a
+    # ticket. Runs inline after save; keep it fast or hand off to a job.
+    attr_accessor :on_submit
+
+    # Per-IP throttle for the public submission endpoint, as keyword arguments
+    # for Rails' rate limiter (Rails 7.2+; ignored on 7.1). Read once when the
+    # controller loads — set it in an initializer. nil disables throttling.
+    attr_accessor :rate_limit
+
+    def initialize
+      @enabled_environments = %w[development staging]
+      @enabled = ->(_request) { true }
+      @authorize_admin = ->(_request) { Rails.env.development? }
+      @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_proofreading'
+      @show_pill = true
+      @pill_label = nil
+      @toggle_param = 'i18n_proofreading'
+      @on_submit = ->(_suggestion) {}
+      @rate_limit = { to: 30, within: 60 }
+    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_proofreading/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module I18nProofreading
+  class Engine < ::Rails::Engine
+    isolate_namespace I18nProofreading
+
+    initializer 'i18n_proofreading.middleware' do |app|
+      app.middleware.use I18nProofreading::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 I18nProofreading.config.environment_enabled? &&
+         !I18n.backend.class.include?(I18nProofreading::Marking::Backend)
+        I18n.backend.class.prepend(I18nProofreading::Marking::Backend)
+      end
+    end
+
+    initializer 'i18n_proofreading.helper' do
+      ActiveSupport.on_load(:action_view) do
+        include I18nProofreading::TagHelper
+      end
+    end
+  end
+end

data/lib/i18n_proofreading/marking.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module I18nProofreading
+  # 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. The tool's own
+    # `i18n_proofreading.*` strings are skipped too: they aren't part of the host
+    # app's translatable copy, so the widget must never mark (or offer to edit)
+    # its own UI.
+    SKIP = /(\A|\.)(number|date|time|datetime|support|i18n_proofreading)(\.|\z)|formats?\z/
+
+    class << self
+      def enabled?
+        Thread.current[:i18n_proofreading_marking] || false
+      end
+
+      def enabled=(value)
+        Thread.current[:i18n_proofreading_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_proofreading/middleware.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module I18nProofreading
+  # 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 I18nProofreading.available?, so nothing happens in a disabled environment.
+  class Middleware
+    COOKIE = 'i18n_proofreading'
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      available = I18nProofreading.available?(request)
+
+      # "?i18n_proofreading=true|false" is a one-shot command, not a sticky URL state:
+      # set the cookie and redirect to the same URL without the parameter. That
+      # keeps the cookie the single source of truth (so the pill's reload can turn
+      # suggest mode off) and stops the parameter from lingering in the address bar.
+      if available && request.get? && !(desired = toggle_override(request)).nil?
+        return toggle_redirect(request, desired)
+      end
+
+      marking = available && cookie_on?(request)
+      Marking.enabled = marking
+
+      status, headers, body = @app.call(env)
+
+      if available && I18nProofreading.config.auto_inject && html?(headers) && !request.xhr?
+        status, headers, body = inject(status, headers, body, marking, csp_nonce(env))
+      end
+
+      [status, headers, body]
+    ensure
+      Marking.enabled = false
+    end
+
+    private
+
+    def cookie_on?(request)
+      !request.cookies[COOKIE].to_s.empty?
+    end
+
+    def toggle_redirect(request, desired)
+      headers = persist_choice({ 'Content-Type' => 'text/html', 'Location' => url_without_toggle(request) }, desired)
+      [303, headers, []]
+    end
+
+    def url_without_toggle(request)
+      query = Rack::Utils.parse_query(request.query_string)
+      query.delete(I18nProofreading.config.toggle_param)
+      built = Rack::Utils.build_query(query)
+      built.empty? ? request.path : "#{request.path}?#{built}"
+    end
+
+    # The request's CSP nonce, so the injected scripts run under a nonce-based
+    # Content-Security-Policy. Reads the value Rails memoizes on the env, which is
+    # the same nonce the CSP header uses. nil when the app sets no nonce.
+    def csp_nonce(env)
+      return nil unless defined?(ActionDispatch::Request)
+
+      ActionDispatch::Request.new(env).content_security_policy_nonce
+    rescue StandardError
+      nil
+    end
+
+    def toggle_override(request)
+      param = I18nProofreading.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
+
+    # The locale the page was actually rendered in, read from its `<html lang>`
+    # attribute. Auto-injection runs after the controller action, so I18n.locale
+    # may already have been reset from whatever the request used — the rendered
+    # `lang` is the reliable record of the page's language. Falls back to the
+    # ambient locale when the page declares none.
+    def page_locale(html)
+      lang = html[/<html[^>]*\blang=["']([^"']+)["']/i, 1]
+      (lang && normalize_locale(lang)) || I18n.locale
+    end
+
+    # Map an HTML lang value ("es", "pt-BR") to a locale the app actually offers,
+    # trying the value as-is, its underscore form, then its language subtag. nil
+    # if none match, so the caller can fall back rather than emit an unknown one.
+    def normalize_locale(lang)
+      available = I18n.available_locales.map(&:to_s)
+      [lang, lang.tr('-', '_'), lang.split(/[-_]/).first].uniq.find { |c| available.include?(c) }&.to_sym
+    end
+
+    def content_type(headers)
+      headers['Content-Type'] || headers['content-type']
+    end
+
+    def inject(status, headers, body, marking, nonce)
+      html = +''
+      body.each { |part| html << part.to_s }
+      body.close if body.respond_to?(:close)
+
+      snippet = Widget.snippet(
+        endpoint: I18nProofreading.config.suggestions_endpoint,
+        locale: page_locale(html),
+        active: marking,
+        nonce: nonce
+      )
+      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_proofreading/version.rb

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