i18n_proofreading 0.12.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd116667dbbc3243bc9eb5ae929db378fd60d6354dc9101cde3c137474272dd
-  data.tar.gz: 67cb971e8e0d957f9ce6ccd6e3a39f102242588e7e6599945267423b7a32c0ba
+  metadata.gz: 6f31aa1eec6874e5a80180fbd106c1f6ea7f073241e234c8b0c9c64ae474ba45
+  data.tar.gz: c1a02f46f915c3fd496793f9b33885026c090fb70b0fcb0474d017ac0c2bbd14
 SHA512:
-  metadata.gz: dd83ae4d457202c63398da204778301533d78c575426591eb4c28acc58a299beab35ccbea8861a468688af0ea09e9a7c67053d299fe0174080377e58ada84b8c
-  data.tar.gz: e88607a7ebc036f1be84553bd88d995b99ca548992ed9e88d519f0f2497759d48933ce7520eed72524d0c804998c15a0d95aaec88384f7447ce94a44fcac6ee6
+  metadata.gz: dfca53a8ba1b338b6bca4b29060c0c5f7ecb8077817d26fc6078d22b971195d7577db3ef7a433f0252213b1214bd09adbdec0daaa66938708a3556e9ca766701
+  data.tar.gz: 9bd50ba50b9a8c43b26839a9467b43cc50c96ba18e25ed0738433d0013ce18606566c61ca3b954022281ee40266701aa2c9efd5f6414baac5e561fa5b21a5338

data/AGENTS.md

@@ -5,7 +5,7 @@ Instructions for coding agents. Two audiences:
 - **[Installing i18n_proofreading into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add in-context translation review or a way for someone to suggest better wording.
 - **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
 
-Requirements: Ruby >= 3.2, Rails >= 7.1. The widget needs the CSRF token from `csrf_meta_tags`, which a standard Rails layout already has.
+Requirements: Ruby 3.2–4.0, Rails 7.1–8.1. The widget needs the CSRF token from `csrf_meta_tags`, which a standard Rails layout already has.
 
 **Read this first: the gem never writes to your locale files, and it is not a production tool.** Both are deliberate, and both are covered below.
 
@@ -151,6 +151,6 @@ Conventions this codebase holds to — follow them rather than the first thing t
 - **The tool never writes to the host's locale files.** That is why there is deliberately no update or destroy route, and why the dashboard is read-only. Do not add an "apply" action that edits YAML.
 - **The widget is injected by middleware and served same-origin**, which is what keeps it working under a nonce-based CSP with `strict-dynamic` across Turbo body swaps. Do not inline it.
 - **Key marking must degrade to plain strings.** A host that reads translations outside a request, or in an environment where the tool is off, has to get ordinary values back.
-- **`lib/i18n_proofreading/dashboard.css` is half shared.** Everything above the `GEM-SPECIFIC` banner is the design system all five gems in the family ship — the same tokens, the same `.page-head`/`.tabs`/`.filters`/`.card`/`.badge`/`button`, the same `.dashboard-shell` + `.record-row` + `.detail-panel` two-pane dashboard — identical in every repo apart from the `ip` prefix. Diff it against a sibling before changing it, and carry the change to the other four. Anything only this gem has goes below the banner. New dashboard markup reuses the shared class names rather than inventing a domain-specific one.
+- **`lib/i18n_proofreading/dashboard.css` is half shared.** Everything above the `GEM-SPECIFIC` banner is the design system all five gems in the family ship — the same tokens, the same `.page-head`/`.tabs`/`.filters`/`.card`/`.badge`/`button`/`.status-switch`, the same `.dashboard-shell` + `.record-row` + `.detail-panel` two-pane dashboard — identical in every repo apart from the `ip` prefix. Diff it against a sibling before changing it, and carry the change to the other four. Anything only this gem has goes below the banner. New dashboard markup reuses the shared class names rather than inventing a domain-specific one.
 - Every user-facing change bumps `lib/i18n_proofreading/version.rb` and adds a `CHANGELOG.md` entry (Keep a Changelog format) that says what it costs, not only what it adds.
 - Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.0.0] - 2026-08-11
+
+- **The documented integration surface is now the stable 1.x contract.**
+  `I18nProofreading.configure`, every generated configuration option,
+  `mount_i18n_proofreading`, `i18n_proofreading_tag`, the toggle parameter,
+  `I18nProofreading::Suggestion`'s documented fields/status helpers/scopes, and
+  the `on_submit` callback will follow semantic versioning. Engine controllers,
+  partials, CSS classes and widget internals remain private implementation.
+- **Hosts that load Action View from an initializer boot normally.** `TagHelper`
+  is required from `lib` before the engine registers its Action View load hook,
+  rather than relying on an `app/helpers` autoload that Rails may not have set
+  up yet. A dummy-host initializer now reproduces that early load on every test
+  boot. The helper constant and `i18n_proofreading_tag` API are unchanged.
+- Supported combinations are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1.
+  Rails now has a `< 9` upper bound: future Rails majors must pass the suite
+  before Bundler treats them as supported.
+- Added a security policy and documented the data a suggestion stores, the
+  production-off default, private vulnerability reporting, and host-owned
+  retention/deletion. Upgrading from 0.12.1 requires no migration or config
+  change.
+- Release validation now runs the normal and browser suites, RuboCop, the
+  widget syntax check and gem build on Ruby 4.0; it verifies the published
+  version and creates the GitHub Release. Generator tests now write only under
+  ignored root `tmp/`, so running the suite no longer rewrites tracked fixtures.
+
+## 0.12.1
+
+- **The demo suggestions now teach the review contract.** Pending explains the
+  inbox decision, applied makes clear that a human edited and committed the
+  locale file, and rejected demonstrates a proposal that changes meaning. The
+  seed is now a compact tutorial for the gem's deliberately read-only role.
+- `i18n_proofreading:seed_demo` updates its existing demo suggestions in place,
+  so rerunning it overwrites edits to those gem-owned rows. Host locale files
+  and non-demo suggestions remain untouched.
+
 ## 0.12.0
 
 - **One design system across the family.** The stylesheet now opens with a
@@ -62,8 +99,6 @@
   does, so a uuid-keyed host gets a uuid table.
 - A `BackboneTest` now fails the build on any of the above regressing.
 
-## [Unreleased]
-
 ## [0.10.6]
 
 - Added `AGENTS.md`: install and integration instructions written for coding

data/README.md

@@ -46,8 +46,8 @@ No layout change needed — the widget injects itself into HTML responses.
 > `%w[development staging]`, and the review dashboard defaults to development
 > only. This is not a production tool.
 
-Ruby >= 3.2 · Rails >= 7.1 · CSRF token comes from `csrf_meta_tags`, already in
-a standard Rails layout.
+Ruby 3.2–4.0 · Rails 7.1–8.1 · CSRF token comes from `csrf_meta_tags`, already
+in a standard Rails layout.
 
 Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
 steps in the order an agent needs them, the gates it tends to get wrong, and the
@@ -273,6 +273,36 @@ to use the localized `i18n_proofreading.pill` key.
 
 </details>
 
+## Compatibility and public API
+
+Starting with 1.0, these documented integration points follow semantic
+versioning: incompatible changes wait for a new major version, while a
+deprecation normally ships in a preceding minor release.
+
+- `I18nProofreading.configure` and the configuration options listed above.
+- `mount_i18n_proofreading at:` and the mounted dashboard root.
+- `i18n_proofreading_tag` for hosts that disable automatic injection.
+- The configured toggle parameter and its `true` / `false` behavior.
+- `I18nProofreading::Suggestion` fields documented under Reviewing
+  suggestions, `STATUSES`, prefixed status helpers/scopes, and `newest_first`.
+- `on_submit`, called with the saved suggestion.
+
+Engine controllers, view partials, CSS classes, generated HTML structure, and
+the JavaScript object behind the widget are implementation details. Integrate
+through the APIs above rather than reopening or linking to those internals.
+
+Supported versions are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1. The gem
+depends on Rails `< 9`; support for a future Rails major is released after that
+major passes the compatibility and browser suites.
+
+### Upgrading from 0.12.1
+
+Change the version requirement and run `bundle update i18n_proofreading`. No
+database migration, generator, initializer change, or data rewrite is needed.
+The `I18nProofreading::TagHelper` constant and `i18n_proofreading_tag` behavior
+are unchanged; only the helper's internal load location moved so hosts that
+configure Action View during initialization can boot reliably.
+
 ## Security
 
 - **Gated on the server** for every marker, endpoint, and injection. Setting
@@ -286,6 +316,12 @@ to use the localized `i18n_proofreading.pill` key.
   survives Turbo visits.
 - **Rate-limited per IP** on the submission endpoint (30/min by default,
   Rails 7.2+).
+- **Host-owned review data.** A row may contain translated text, proposed text,
+  a comment, page URL, and optional author fields. The host controls access,
+  backups, retention, and deletion.
+
+Report vulnerabilities privately through the process in
+[SECURITY.md](SECURITY.md), not through a public issue.
 
 ## Development
 
@@ -296,7 +332,8 @@ bundle exec rake test:system  # browser tests (headless Chrome)
 bundle exec rubocop
 ```
 
-Tests run against a dummy Rails app in `test/dummy`.
+Tests run against a dummy Rails app in `test/dummy`. CI covers Ruby 3.2–4.0
+against Rails 7.1–8.1, plus the real browser flow on Ruby 4.0.
 
 ## One family
 

data/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released for the latest 1.x version. If a report also
+affects the newest 0.x release, a backport may be published when the fix is
+small and the affected application cannot upgrade immediately.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/i18n_proofreading/security/advisories/new)
+and include the affected version, a minimal reproduction, impact, and any known
+workaround. Credentials, session cookies, private application URLs, customer
+text, and production database contents should not be included.
+
+Public disclosure should wait until a fixed version is available and affected
+users have had a reasonable opportunity to upgrade.
+
+## Data and deployment boundary
+
+The proofreading widget is enabled only in development and staging by default.
+Adding production to `enabled_environments` is unsupported: key marking changes
+rendered application text and the suggestion endpoint is intended for trusted
+review environments.
+
+A suggestion can store its translation key, locale, current and proposed text,
+comment, page URL, status, timestamps, and optional host-provided author id and
+label. Host applications own that data, its backups, retention period, access
+controls, and deletion. Delete a suggestion with ordinary Active Record when a
+reviewer or application policy requires erasure:
+
+```ruby
+I18nProofreading::Suggestion.find(id).destroy!
+```
+
+The mounted dashboard is independently protected by `authorize_admin`. Outside
+development it fails closed until the host explicitly grants access.

data/lib/i18n_proofreading/dashboard.css

@@ -144,6 +144,19 @@
   & .actions form { display: inline; }
   & .form-actions { padding-top: 12px; }
 
+  /* Status switch: one pill holding every state a record can be in, the state it
+     is in now lit. Each other segment is a submit button, so moving a record
+     takes one click and no JavaScript; the current segment is a `type="button"`
+     so clicking it cannot re-file the record it is already filed under. Two
+     states or five, the pill sizes itself. A gem tints the lit segment with its
+     own status colour — see the `GEM-SPECIFIC` section. */
+  & .status-switch { display: inline-flex; flex: 0 0 auto; margin: 0; padding: 3px; border: 1px solid var(--ip-border); border-radius: 999px; background: var(--ip-bg); }
+  & .status-switch button { min-height: 30px; padding: 0 12px; border: 0; border-radius: 999px; background: none; color: var(--ip-muted); font-size: 13px; font-weight: 700; white-space: nowrap; transition: background .16s ease, color .16s ease; }
+  & .status-switch button:hover { border: 0; background: color-mix(in srgb, var(--ip-muted) 12%, transparent); color: var(--ip-text); }
+  & .status-switch button.current { background: var(--ip-surface); color: var(--ip-text); box-shadow: 0 1px 2px rgba(15, 23, 42, .12); cursor: default; }
+  & .status-switch button.current:hover { background: var(--ip-surface); }
+  & .panel-head .status-switch { margin-left: auto; }
+
   & .card { overflow: hidden; border: 1px solid var(--ip-border); border-radius: 12px; background: var(--ip-surface); }
   & .card.pad { padding: 16px; overflow: visible; }
   & table { width: 100%; border-collapse: collapse; }
@@ -266,6 +279,7 @@
     & .dashboard-detail .detail-panel { min-height: calc(100vh - 64px); }
     & .mobile-back { display: block; flex: 0 0 auto; margin: 4px 0 10px; font-size: 13px; }
     & .panel-head h1 { font-size: 18px; }
+    & .status-switch button { padding: 0 9px; font-size: 12px; }
     & dl { grid-template-columns: 1fr; gap: 3px; }
     & dd { margin-bottom: 8px; }
   }

data/lib/i18n_proofreading/seeds.rb

@@ -7,34 +7,37 @@ module I18nProofreading
         translation_key: 'dashboard.title',
         locale: 'en',
         old_value: 'Dashboard',
-        proposed_value: 'Overview',
-        comment: 'Shorter and clearer for the first screen.',
+        proposed_value: 'Product overview',
+        comment: 'Start here: pending suggestions are the review inbox. Compare the rendered wording and ' \
+                 'page context, then decide whether the proposed copy belongs in your locale file.',
         page_url: '/dashboard',
         status: 'pending',
         author_id: 'i18n-proofreading-demo:reviewer',
-        author_label: 'Demo Reviewer'
+        author_label: 'Demo reviewer · needs a decision'
       },
       {
         translation_key: 'billing.cta',
         locale: 'en',
         old_value: 'Go',
         proposed_value: 'Update billing details',
-        comment: 'The button should say what will happen.',
+        comment: 'Applied is bookkeeping, not automation: a maintainer copied this clearer call to action ' \
+                 'into config/locales and committed the change. The gem never edits YAML for you.',
         page_url: '/billing',
         status: 'applied',
         author_id: 'i18n-proofreading-demo:copywriter',
-        author_label: 'Demo Copywriter'
+        author_label: 'Demo copywriter · applied by a human'
       },
       {
         translation_key: 'settings.cancel',
         locale: 'fr',
         old_value: 'Annuler',
         proposed_value: 'Supprimer le compte',
-        comment: 'Rejected example: this changes the meaning.',
+        comment: 'Rejected on purpose: the proposal means “Delete the account,” not “Cancel.” The original ' \
+                 'translation stays the source of truth, and the rejected row preserves the review decision.',
         page_url: '/settings',
         status: 'rejected',
         author_id: 'i18n-proofreading-demo:reviewer',
-        author_label: 'Demo Reviewer'
+        author_label: 'Demo reviewer · meaning changed'
       }
     ].freeze
 

data/{app/helpers → lib}/i18n_proofreading/tag_helper.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 module I18nProofreading
-  # Lets a host place the widget explicitly (`<%= i18n_proofreading_tag %>` at the end
-  # of a layout) instead of relying on auto-injection. Renders nothing unless the
-  # tool is available for the current request.
+  # Lets a host place the widget explicitly (`<%= i18n_proofreading_tag %>` at
+  # the end of a layout) instead of relying on auto-injection. This lives under
+  # lib and is required before the engine registers its Action View load hook:
+  # a host initializer may load Action View before Rails sets up application
+  # autoloaders, when an app/helpers constant cannot be resolved yet.
   module TagHelper
     def i18n_proofreading_tag
       return ''.html_safe unless I18nProofreading.available?(request)

data/lib/i18n_proofreading/version.rb

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

data/lib/i18n_proofreading.rb

@@ -4,6 +4,7 @@ require 'i18n_proofreading/version'
 require 'i18n_proofreading/configuration'
 require 'i18n_proofreading/marking'
 require 'i18n_proofreading/widget'
+require 'i18n_proofreading/tag_helper'
 require 'i18n_proofreading/middleware'
 require 'i18n_proofreading/seeds'
 require 'i18n_proofreading/engine'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: i18n_proofreading
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 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
@@ -39,13 +45,13 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - app/controllers/concerns/i18n_proofreading/request_context.rb
 - app/controllers/i18n_proofreading/application_controller.rb
 - app/controllers/i18n_proofreading/dashboard_controller.rb
 - app/controllers/i18n_proofreading/submissions_controller.rb
 - app/controllers/i18n_proofreading/suggestions_controller.rb
 - app/controllers/i18n_proofreading/widgets_controller.rb
-- app/helpers/i18n_proofreading/tag_helper.rb
 - app/models/i18n_proofreading/application_record.rb
 - app/models/i18n_proofreading/suggestion.rb
 - app/views/i18n_proofreading/shared/_dashboard.html.erb
@@ -91,6 +97,7 @@ files:
 - lib/i18n_proofreading/marking.rb
 - lib/i18n_proofreading/middleware.rb
 - lib/i18n_proofreading/seeds.rb
+- lib/i18n_proofreading/tag_helper.rb
 - lib/i18n_proofreading/version.rb
 - lib/i18n_proofreading/widget.js
 - lib/i18n_proofreading/widget.rb
@@ -101,6 +108,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/yshmarov/i18n_proofreading
   changelog_uri: https://github.com/yshmarov/i18n_proofreading/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yshmarov/i18n_proofreading/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -116,7 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: 'In-context i18n proofreading for Rails: click any translated string and
   suggest a fix.'