{"id":51881175,"url":"https://github.com/yshmarov/i18n_proofreading","last_synced_at":"2026-07-27T15:00:32.598Z","repository":{"id":372544801,"uuid":"1306800890","full_name":"yshmarov/i18n_proofreading","owner":"yshmarov","description":"🌍 In-context i18n proofreading for Rails: click any translated string in your running app and suggest a better wording. Zero UI dependencies, no build step.","archived":false,"fork":false,"pushed_at":"2026-07-25T21:41:28.000Z","size":3678,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-26T14:11:28.549Z","etag":null,"topics":["i18n","internationalization","localization","rails","rails-engine","ruby","ruby-gem","translations"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/i18n_proofreading","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yshmarov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-20T16:25:56.000Z","updated_at":"2026-07-25T21:41:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yshmarov/i18n_proofreading","commit_stats":null,"previous_names":["yshmarov/i18n-feedback"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/yshmarov/i18n_proofreading","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshmarov%2Fi18n_proofreading","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshmarov%2Fi18n_proofreading/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshmarov%2Fi18n_proofreading/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshmarov%2Fi18n_proofreading/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yshmarov","download_url":"https://codeload.github.com/yshmarov/i18n_proofreading/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshmarov%2Fi18n_proofreading/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35955551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-27T02:00:06.776Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","internationalization","localization","rails","rails-engine","ruby","ruby-gem","translations"],"created_at":"2026-07-25T13:01:36.288Z","updated_at":"2026-07-27T15:00:32.548Z","avatar_url":"https://github.com/yshmarov.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i18n_proofreading\n\n[![Gem Version](https://img.shields.io/gem/v/i18n_proofreading)](https://rubygems.org/gems/i18n_proofreading)\n[![Downloads](https://img.shields.io/gem/dt/i18n_proofreading)](https://rubygems.org/gems/i18n_proofreading)\n[![CI](https://github.com/yshmarov/i18n_proofreading/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/i18n_proofreading/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)\n\nIn-context translation proofreading for Rails.\n\n`i18n_proofreading` renders every translated string alongside its i18n key in the\nenvironments you choose, lets a reviewer click any string in the running app and\nsuggest a better wording, and stores those suggestions for a developer to apply.\nIt is meant for development and staging, never production.\n\n![Click any string in your running app and suggest a better wording](i18n-proofreading-demo.gif)\n\n\u003cvideo src=\"https://github.com/yshmarov/i18n_proofreading/raw/main/i18n-proofreading-demo-640-high.mp4\" controls muted playsinline width=\"640\"\u003e\n  Your browser can't play this video —\n  \u003ca href=\"https://github.com/yshmarov/i18n_proofreading/raw/main/i18n-proofreading-demo-640-high.mp4\"\u003edownload it here\u003c/a\u003e.\n\u003c/video\u003e\n\n- **Zero UI dependencies.** The widget is plain JavaScript and styles itself. No\n  Tailwind, no daisyUI, no Stimulus, no importmap, no build step.\n- **Zero layout changes.** The widget is injected into HTML responses\n  automatically (opt out and place it yourself if you prefer).\n- **Trigger it your way.** Use the built-in floating pill, or hide it and switch\n  suggest mode on from your own link (a nav item, a menu, anywhere).\n- **Pluggable gating and attribution.** You decide which environments and which\n  users see the tool, and how a suggestion is attributed.\n\n## How it works\n\n1. In an enabled environment, the I18n backend appends a hidden `⟦some.key⟧`\n   marker to each translated string. Markers are only emitted while a reviewer\n   has the tool switched on (a cookie), so pages are clean by default.\n2. The browser widget strips every marker out of the DOM on load and remembers\n   which key produced each piece of text.\n3. Clicking a string opens a popover showing the current text, any pending\n   suggestions, and a field to propose a new wording.\n4. Suggestions are `POST`ed to the mounted engine and stored in the\n   `i18n_proofreading_suggestions` table for you to review and apply.\n\n## Turbo\n\nWorks with Turbo Drive out of the box. Turbo replaces `\u003cbody\u003e` on every visit,\nwhich would take the pill and the active-mode highlighting with it, so the\nwidget registers its document-level listeners once and re-renders on\n`turbo:load`. The pill survives navigation without a full reload.\n\n## Requirements\n\n- Ruby \u003e= 3.2\n- Rails \u003e= 7.1\n\n## Installation\n\nAdd the gem:\n\n```ruby\n# Gemfile\ngem \"i18n_proofreading\"\n```\n\n```bash\nbundle install\nbin/rails generate i18n_proofreading:install\nbin/rails db:migrate\n```\n\nThe generator:\n\n- writes `config/initializers/i18n_proofreading.rb`,\n- creates the `i18n_proofreading_suggestions` migration,\n- mounts the engine in `config/routes.rb`:\n\n  ```ruby\n  mount I18nProofreading::Engine =\u003e \"/i18n_proofreading\"\n  ```\n\nBoot the app in development and look for the **“Suggest edits”** pill in the\nbottom-left corner. Click it to turn on suggest mode, then click any text to\npropose a fix. Press `Esc` (or the pill) to exit.\n\n\u003e The widget reads the CSRF token from `\u003cmeta name=\"csrf-token\"\u003e`, which\n\u003e `csrf_meta_tags` in your layout already provides in a standard Rails app.\n\n## Configuration\n\nEverything is optional; the defaults work out of the box in development.\n\n```ruby\n# config/initializers/i18n_proofreading.rb\nI18nProofreading.configure do |config|\n  # Environments the tool is active in.\n  config.enabled_environments = %w[development staging]\n\n  # Extra per-request gate. Return false to hide the tool. Receives the request.\n  config.enabled = -\u003e(request) { true }\n\n  # Who may open the triage dashboard. Independent of the gates above; defaults\n  # to development only. Wire it to your own admin check to open it elsewhere.\n  config.authorize_admin = -\u003e(request) { Rails.env.development? }\n\n  # Attribute a suggestion to a user (optional). Return an object responding to\n  # #id, or nil. Receives the request.\n  config.current_user = -\u003e(request) { nil }\n\n  # Label shown for the author in the \"already suggested\" list.\n  config.author_label = -\u003e(user) { user.try(:email) }\n\n  # Inject the widget automatically. Set false to place it yourself.\n  config.auto_inject = true\n\n  # Show the floating \"Suggest edits\" pill. Set false to drive suggest mode from\n  # your own link instead (see below).\n  config.show_pill = true\n\n  # Query parameter that toggles suggest mode.\n  config.toggle_param = \"i18n_proofreading\"\n\n  # Keep in sync with the `mount` in config/routes.rb.\n  config.mount_path = \"/i18n_proofreading\"\n\n  # Per-IP throttle on the submission endpoint, passed to Rails' built-in rate\n  # limiter (Rails 7.2+; ignored on 7.1). Set nil to disable.\n  config.rate_limit = { to: 30, within: 60 }\nend\n```\n\n### Toggling suggest mode from your own link\n\nPrefer a menu item over the floating pill? You can drive suggest mode from any\nlink in your own UI — a nav item, a sidebar entry, a footer — and optionally hide\nthe pill (the two can also coexist):\n\n```ruby\nconfig.show_pill = false # optional\n```\n\nA one-way \"turn it on\" link is just the toggle parameter:\n\n```erb\n\u003c%= link_to t(\"i18n_proofreading.start\"), \"?i18n_proofreading=true\" %\u003e\n```\n\nFor a single control that flips both ways, read the current state from the\n`i18n_proofreading` cookie and point at the opposite state. The gem ships `start`\nand `stop` labels under the `i18n_proofreading.*` scope in every bundled language,\nso a localized toggle needs no keys of your own:\n\n```erb\n\u003c% if I18nProofreading.available?(request) %\u003e\n  \u003c% suggesting = cookies[:i18n_proofreading].present? %\u003e\n  \u003c%= link_to (suggesting ? t(\"i18n_proofreading.stop\") : t(\"i18n_proofreading.start\")),\n              \"?#{I18nProofreading.config.toggle_param}=#{!suggesting}\" %\u003e\n\u003c% end %\u003e\n```\n\nGood to know:\n\n- `?i18n_proofreading=true` turns suggest mode on, `false` turns it off. The state is\n  stored in the `i18n_proofreading` cookie, and the middleware then redirects to the\n  same URL without the parameter — so it never sticks in the address bar and the\n  cookie stays the single source of truth. `Esc` (or the pill) also exits.\n- These links keep working **while suggest mode is active**. The widget freezes\n  ordinary navigation during proofreading (so a stray click can't leave the page\n  mid-edit), but any link carrying the toggle parameter is exempt — so a \"Disable\"\n  item in your nav always gets you out.\n- The `i18n_proofreading.*` keys are **safe to run through `I18n.t`** — that scope is\n  exempt from key-marking, so the tool never flags its own controls as editable.\n  Use the bundled `i18n_proofreading.start` / `i18n_proofreading.stop` labels (or your own\n  keys); either way, no plain-literal workaround is needed.\n\n### Gating examples\n\n```ruby\n# Only signed-in staff (however your app resolves that):\nconfig.enabled = -\u003e(request) { request.env[\"warden\"]\u0026.user\u0026.staff? }\n\n# Behind a feature flag:\nconfig.enabled = -\u003e(request) { Flipper.enabled?(:i18n_proofreading) }\n```\n\n### Resolving the current user\n\n`current_user` (optional — it attributes suggestions) and the gates all\nreceive the raw request, so they work with whatever auth you have:\n\n```ruby\n# Devise / Warden:\nconfig.current_user = -\u003e(request) { request.env[\"warden\"]\u0026.user }\n\n# Rails 8 built-in auth (bin/rails generate authentication):\nconfig.current_user = lambda do |request|\n  token = request.cookies[\"session_token\"]\n  Session.find_signed(token)\u0026.user if token\nend\n```\n\n### Placing the widget yourself\n\nSet `config.auto_inject = false` and drop the helper at the end of your layout:\n\n```erb\n\u003c%= i18n_proofreading_tag %\u003e\n```\n\nIt renders nothing unless the tool is available for the request.\n\n### Localizing the widget UI\n\nThe pill and the suggestion popover speak the app's language: every string\nresolves through Rails I18n under the `i18n_proofreading.*` scope and follows the\nlanguage the page was rendered in (its `\u003chtml lang\u003e`, falling back to\n`I18n.locale`). Translations ship out of the box for English plus 25 more\nlanguages — Arabic, Bengali, Bulgarian, Chinese (Simplified), Croatian, Dutch,\nFrench, German, Greek, Hindi, Indonesian, Italian, Japanese, Korean,\nLuxembourgish, Polish, Portuguese, Romanian, Russian, Spanish, Thai, Turkish,\nUkrainian, Urdu and Vietnamese — so the tool is already localized for most apps.\nRTL locales (Arabic, Urdu, …) render the popover right-to-left automatically.\n\nAny key you haven't translated falls back to English, so a partially translated\nlocale never leaves a control blank. To add a language, or reword the bundled\ncopy, define the keys in your own locale files (yours win over the gem's):\n\n```yaml\n# config/locales/fr.yml\nfr:\n  i18n_proofreading:\n    pill: \"Proposer des corrections\"\n    pill_active: \"En cours — appuyez pour quitter (Échap)\"\n    title: \"Proposer une correction de traduction\"\n    current_text: \"Texte actuel\"\n    suggested_text: \"Texte proposé\"\n    comment: \"Commentaire\"\n    comment_placeholder: \"Note facultative pour le développeur\"\n    prior_title: \"Déjà proposé (en attente)\"\n    cancel: \"Annuler\"\n    save: \"Envoyer la suggestion\"\n    error_blank: \"Veuillez saisir une suggestion.\"\n    error_save: \"Impossible d'enregistrer la suggestion.\"\n```\n\n`config.pill_label` still overrides the pill text with a fixed string if you set\nit; leave it `nil` (the default) to use the localized `i18n_proofreading.pill` key.\n\n### Light / dark / system appearance\n\nThe widget follows the reviewer's operating-system appearance via\n`prefers-color-scheme` — no configuration needed. The pill and popover render on a\ndark surface when the system is in dark mode and a light surface otherwise; the\nblue accent stays the same in both.\n\n## Reviewing suggestions\n\n### Review dashboard\n\nMounted at your `mount_path` (default `/i18n_proofreading`), the engine root is a\nbuilt-in **read-only** review board: pending / applied / rejected tabs with\ncounts, a per-locale filter, and each suggestion shown as current-vs-proposed\nwith its comment and author. It's plain server-rendered HTML with its own\nstyling — no host assets or JS framework needed.\n\nIt is deliberately read-only. The gem never writes to your locale files, so it\ndoesn't pretend to: you review the suggestions here, then make the edits in your\nown `config/locales/*.yml`. (A suggestion's `status` still exists on the model\nfor your own tracking — set it from the console — and is the groundwork for a\nfuture \"apply to locale file\" feature.)\n\nIt has its own gate, `config.authorize_admin`, **defaulting to development\nonly** — so a fresh install never exposes it in production. Point it at your own\nadmin check to open it elsewhere:\n\n```ruby\nconfig.authorize_admin = -\u003e(request) { request.env[\"warden\"]\u0026.user\u0026.admin? }\n```\n\nThe gate is independent of `enabled` / `enabled_environments`: the widget can be\ndev/staging-only while a maintainer still triages from production.\n\n### From the console\n\nSuggestions are also ordinary records:\n\n```ruby\nI18nProofreading::Suggestion.where(status: \"pending\").newest_first.each do |s|\n  puts \"#{s.locale} #{s.translation_key}: #{s.old_value.inspect} -\u003e #{s.proposed_value.inspect}\"\nend\n```\n\nEach row stores `translation_key`, `locale`, `old_value`, `proposed_value`,\n`comment`, `page_url`, `status`, and optional `author_id` / `author_label`.\n\nEvery suggestion has a `status` — one of `pending`, `applied`, or `rejected`\n(`I18nProofreading::Suggestion::STATUSES`), backed by an Active Record enum. New\nsuggestions start `pending`; once you apply a wording to your locale files or\ndecide against it, set the status accordingly so the popover stops offering it\nas pending context:\n\n```ruby\nsuggestion.status_applied!          # bang setter\nsuggestion.status_applied?          # =\u003e true\nI18nProofreading::Suggestion.status_pending.newest_first  # scope per status\n```\n\n### Getting notified\n\nTo be pinged when a suggestion comes in, set `on_submit`. It's called with the\nsaved `Suggestion` right after it's stored — notify Slack, send an email, open a\nticket. It runs inline in the request, so keep it fast or hand off to a job:\n\n```ruby\nconfig.on_submit = -\u003e(suggestion) { SuggestionMailer.with(suggestion:).created.deliver_later }\n```\n\n## Security\n\n- The tool is gated **on the server** for every marker, endpoint, and injection.\n  Setting the cookie by hand does nothing outside an enabled environment where\n  `config.enabled` returns true.\n- Format and lookup namespaces (`number.*`, `date.*`, `*_html` formats, etc.) are\n  never marked, so currency and date formatting are unaffected.\n- The injected widget code carries the request's Content-Security-Policy nonce\n  (the same one `ActionDispatch` emits), so it runs under a nonce-based\n  `script-src` policy — including `strict-dynamic` — with no configuration. It is\n  a no-op when the app sets no CSP nonce. The runtime config is shipped as a\n  `\u003cscript type=\"application/json\"\u003e` block (data, not code), so it needs no nonce\n  and stays correct across Turbo visits.\n\n## Development\n\n```bash\nbin/setup        # or: bundle install\nbundle exec rspec\n```\n\nTests run against a dummy Rails app under `spec/dummy`.\n\n## License\n\nReleased under the [MIT License](MIT-LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyshmarov%2Fi18n_proofreading","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyshmarov%2Fi18n_proofreading","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyshmarov%2Fi18n_proofreading/lists"}