i18n-keyless-rails 3.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 633d0e2996fa5a44ee8797a9ae88800193649f7044e6656c9fcf72d0ea91bb96
+  data.tar.gz: 00074f4d1e5cd3e49ec2457f709174aff440b78c4be7e11a18ee5ec842a09b5c
+SHA512:
+  metadata.gz: a565de147537f2032e4b34f6895dc9700ef8f778eee41d08ff67761fece8887d574a9c15c90b331ac31ac1fc780994906211376b6273e5c0bba444135e7aeffc
+  data.tar.gz: 95a91cd608ba7f4097db861ab0d74c89aed212047ddd6b86ec23d5cc8cd67bb00ad0c3b4d47825e9a711f30473f81bde53cc65d506dbfac5738c29620b44261e

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arnaud Ambroselli
+
+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,237 @@
+# i18n-keyless for Ruby on Rails
+
+Keyless translations for Rails. Write the source string where a key would go,
+`t('Welcome to our app')`, and it resolves through the i18n-keyless API: a missing string is
+translated by AI once, for every language, and served from `Rails.cache` from then on. No more
+`config/locales/*.yml` files to maintain by hand.
+
+## Quick start
+
+```bash
+bundle add i18n-keyless-rails
+```
+
+```dotenv
+# .env
+I18N_KEYLESS_API_KEY=your-key        # https://i18n-keyless.com/#get-api-key
+I18N_KEYLESS_LANGUAGES=en,fr,es      # every language your app serves
+```
+
+```erb
+<h1><%= t('Welcome to our app') %></h1>
+<p><%= t('Welcome %{name}', name: current_user.name) %></p>
+<%= i18nk('8 heures', context: 'duration') %>
+```
+
+Done. `t('Welcome to our app')` returns the translation for `I18n.locale`.
+
+That is the whole integration: one gem, two `.env` lines, and your source strings where the
+keys used to be. Rails 7.0 to 8.x, Ruby >= 3.1.
+
+## How it works
+
+1. Nothing happens for the primary language: the source string is the translation.
+2. The gem is an `I18n` backend chained **after** your own: `I18n::Backend::Chain.new(your
+   backend, I18nKeyless::Backend.new)`. A key found in `config/locales/*.yml` wins and never
+   reaches the API. The first `t()` call that misses in another locale loads that locale's
+   dictionary from `Rails.cache`. On the very first request ever for that language, it is
+   fetched from the API (`GET /translate/{lang}`) and stored.
+3. A string the dictionary does not have is returned as-is (the source text, with `%{name}`
+   placeholders replaced by I18n), and recorded. The request is never blocked by a miss.
+4. After the response is sent (a Rack middleware closes the body), the recorded strings are
+   sent to `POST /translate` with the configured `languages` (plus the primary), deduplicated
+   by key and context, at most 30 in flight at once, and the answers are merged into the
+   cache. The next request has them. Without `I18N_KEYLESS_LANGUAGES` nothing is sent: the
+   API stores the list it receives as the project's languages, so an incomplete list would
+   damage every other client on the same key. One warning is logged per process.
+5. A dictionary older than `cache_ttl` is still served, then revalidated after the response
+   with its `ETag` (`If-None-Match`): an unchanged dictionary costs a bodyless `304`.
+6. Usage analytics, like the node SDK: the date each string was last served is recorded and
+   the cumulative map is sent to `POST /translate/last-used-translations` after the response,
+   at most once every 10 s across all your processes (a lock in the cache). It feeds the
+   dashboard's "last used" column so unused strings can be pruned. A failed POST never
+   affects the response; the map waits in the cache for a later request.
+   `I18N_KEYLESS_USAGE=false` switches it off.
+
+Every API call has a 10 s timeout and is retried twice with backoff (500 ms, 1500 ms) on a
+network error, a timeout, a `429` or a `5xx`. Any other `4xx` is not retried. Nothing ever
+raises: on failure the page shows the source text, and the failure is remembered for 60 s so
+the API is not hammered.
+
+## Which strings are keyless
+
+Rails keys and source strings share one `t()`. The rule (`I18nKeyless.keyless_key?`):
+
+- a **Rails key** is a Symbol, a key with a `scope:`, or a lowercase identifier path:
+  `t(:hello)`, `t('hello')`, `t('users.index.title')`, `t('.title')` (lazy lookup),
+  `t('activerecord.errors.models.user')`. Those go to your YAML files, as before, and are
+  never sent to the API. A missing one is still a missing translation.
+- everything else is a **source string**: a space, an uppercase letter or a punctuation mark
+  is enough. `t('Welcome to our app')`, `t('Bonjour')`, `t('Bonjour. Ça va ?')` (a dot in a
+  source string is not a separator).
+
+For a lowercase one-word source string (`close`, `cancel`) use the helper, which never
+treats its argument as a key: `i18nk('close')`. The rule is `config.rails_key_pattern`
+(default `/\A[a-z0-9_]+(\.[a-z0-9_]+)*\z/`); set it to `nil` to make every string keyless.
+
+## Configuration
+
+```ruby
+# config/initializers/i18n_keyless.rb (optional: every value has an .env counterpart)
+I18nKeyless.configure do |c|
+  c.api_key = ENV.fetch("I18N_KEYLESS_API_KEY")
+  c.languages = %w[en fr es]
+  c.primary = "en"
+  c.cache = Rails.cache
+end
+```
+
+| Config | Env | Default | What it is |
+| --- | --- | --- | --- |
+| `enabled` | `I18N_KEYLESS_ENABLED` | `true` | `false` switches the gem off: Rails behaves as without it. |
+| `api_key` | `I18N_KEYLESS_API_KEY` | none | Your project's key. Without it the gem stays inactive. |
+| `api_url` | `I18N_KEYLESS_API_URL` | `https://api.i18n-keyless.com` | The official service, or your own backend / proxy that speaks the same wire format. |
+| `primary` | `I18N_KEYLESS_PRIMARY_LANG` | `I18n.default_locale` | The language your source strings are written in (`en`, `fr`, `pt-BR`, `zh-Hans`...). A Rails locale (`pt_BR`, `:"zh-CN"`) is accepted. |
+| `languages` | `I18N_KEYLESS_LANGUAGES` | empty | Required for translation. Every language your app serves, comma separated (`en,fr,es`) or an array. A new string is translated into all of them at once, and the API stores the list as the project's languages. When empty, missing strings are served as their source text and never sent; one warning is logged. |
+| `namespace` | `I18N_KEYLESS_NAMESPACE` | `default` | The i18n-keyless namespace of the `t()` strings. |
+| `cache` | | `Rails.cache` | Any `ActiveSupport::Cache::Store` (memory, file, Redis, Memcached, the database). Outside Rails: a `MemoryStore`. |
+| `cache_ttl` | `I18N_KEYLESS_CACHE_TTL` | `3600` | Seconds a dictionary is served without asking the API. After that it is revalidated with its `ETag` after the response. |
+| `cache_prefix` | | `i18n-keyless` | Prefix of every cache key the gem writes. |
+| `timeout` | | `10` | HTTP timeout in seconds, per attempt. |
+| `retry` | | `[500, 1500]` | Backoff in milliseconds between retries: two entries, two retries. |
+| `concurrency` | | `30` | Maximum `POST /translate` requests in flight at once. |
+| `usage` | `I18N_KEYLESS_USAGE` | `true` | Usage analytics: the date each string was last served, POSTed at most once every 10 s. `false` disables it. |
+| `queue` | `I18N_KEYLESS_QUEUE` | none | An ActiveJob queue name: the misses of a request are enqueued as one `I18nKeyless::TranslateMissingKeysJob` instead of being sent after the response. |
+| `logger` | | `Rails.logger` | Where the `i18n-keyless:` warnings go. |
+| `rails_key_pattern` | | see above | The Rails-key rule. `nil`: every string is keyless. |
+
+`I18N_KEYLESS_LANGUAGES` is the list the API translates a new string into, and the list it
+stores as your project's languages (it replaces the previous one, like the `supported` list
+the JavaScript SDKs send). A locale that is not in the list is served, but never translated.
+
+Rails validates `I18n.locale` against `I18n.available_locales`, which it derives from the
+YAML files present. An app that serves a locale with no YAML file lists it explicitly:
+`config.i18n.available_locales = %i[en fr es]`.
+
+## Locales
+
+Rails locales are mapped onto the 48 i18n-keyless codes: `:fr` is `fr`, `:"pt-BR"` and
+`pt_BR` are `pt-BR`, `zh_CN` is `zh-Hans`, `zh_TW` is `zh-Hant`, `en_US` is `en`, `fr_FR` is
+`fr`, `es-419` is `es-MX`. A locale no code matches (`xx`) is left alone: `t()` returns the
+source text and nothing is sent. The full list is `I18nKeyless::Locale::AVAILABLE_LANGS`.
+
+## Context: one string, two meanings
+
+`8 heures` is "8 hours" in a duration and "8 AM" on a clock. Pass a `context`, through `t()`
+or through the `i18nk` helper (mixed into views, controllers, mailers and jobs):
+
+```ruby
+t('8 heures', context: 'duration')            # "8 hours"
+i18nk('8 heures', context: 'clock time')      # "8 AM"
+i18nk('Bienvenue %{name}', name: user.name, context: 'greeting')
+i18nk('Payer', namespace: 'checkout')         # an i18n-keyless namespace
+I18nKeyless.t('Payer', namespace: 'checkout') # the same, outside a view
+```
+
+The string is stored as `key__context`, exactly like the JavaScript SDKs, so the dashboard
+and every other SDK see the same entry.
+
+Placeholders are I18n's job: write `%{name}` in the source string, pass `name:` as an
+option, and I18n replaces it after the translation. The SDKs' `replace` option has no
+equivalent here because I18n already does it.
+
+`i18nk(text, values = nil, context: nil, locale: nil, namespace: nil, **values)`.
+
+## Cache
+
+Dictionaries live in `Rails.cache` under `i18n-keyless:{key-hash}:dict:{namespace}:{lang}`
+(the same layout as the Laravel port), stored without expiry. `cache_ttl` is not their
+lifetime: it is how long they are served without revalidation, so a stale dictionary is
+never thrown away before the API has confirmed a newer one. To force a refetch,
+`Rails.cache.clear` (or delete those keys). `I18n.reload!` forgets the dictionaries a
+process holds and re-reads the cache.
+
+Every process (Puma workers, Sidekiq workers) keeps the loaded dictionaries between
+requests; they are refreshed when a revalidation brings a new dictionary, and after each
+`POST /translate`. A dashboard edit reaches a running process at the next revalidation, at
+most `cache_ttl` seconds later. The miss guard and the usage lock live in the cache too:
+with a `:memory_store` they are per process, so use a shared store (Redis, Memcached, the
+database, the file store) in production, as Rails recommends anyway.
+
+## Limitations
+
+- **Plurals.** `t('Il y a %{count} pommes', count: n)` sends one source string and I18n
+  replaces `%{count}`; the pluralisation rules of YAML (`one:` / `other:`) do not apply to a
+  source string. Prefer one `i18nk()` per plural form with a `context` (`context: 'one'`,
+  `context: 'other'`), or keep plurals in YAML files, which Rails keeps loading.
+- **HTML safety.** A source string is a plain string: ERB escapes it like any `t()` result.
+  The `_html` key suffix convention does not apply to a source string.
+- **One key space per locale.** The lines of every namespace are looked up by the same `t()`;
+  pass `namespace:` on the call, or set `I18N_KEYLESS_NAMESPACE` for the whole app.
+- **Misses are deduplicated by key AND context** (the SDK queue ignores the context), so two
+  contexts of one string on one page are both translated after that page.
+- **Usage analytics** count the strings served by this gem only. A string served from a
+  YAML file never reaches it, so it is not counted.
+- **Threads.** One translator per process, shared by every thread. The misses of concurrent
+  requests are flushed together by whichever response finishes first (the cache guard keeps
+  each one from being POSTed twice).
+
+## Outside Rails
+
+The gem needs only `i18n` and `activesupport`. In a plain Ruby, Sinatra or Hanami app:
+
+```ruby
+require "i18n_keyless"
+
+I18nKeyless.configure do |c|
+  c.api_key = ENV.fetch("I18N_KEYLESS_API_KEY")
+  c.languages = %w[en fr]
+  c.cache = ActiveSupport::Cache::MemoryStore.new   # or any store
+end
+I18nKeyless.install!                                # chains the backend after I18n.backend
+use I18nKeyless::Middleware                         # Rack: flush after each response
+I18nKeyless.t("Bonjour", locale: :en)               # without the helper
+I18nKeyless.flush                                   # a script: send the misses before exit
+```
+
+## Self-hosted backend or proxy
+
+Point `I18N_KEYLESS_API_URL` at a server that speaks the three-route wire format
+(`GET /translate/{lang}`, `POST /translate`, `POST /translate/last-used-translations`).
+See https://docs.i18n-keyless.com/docs/guides/proxy-mode. Every request carries
+`Authorization: Bearer <api_key>`, `Version: 3.5.0` (the wire dialect: v3 language codes) and
+`sdk: rails` (a server label, counted like `node`: by its connection, not by a device id).
+
+## Publishing to RubyGems
+
+This directory lives inside the `i18n-keyless` monorepo and is not an npm workspace. The
+gem builds from here:
+
+```bash
+cd ports/rails
+gem build i18n-keyless-rails.gemspec
+gem push i18n-keyless-rails-3.5.0.gem
+```
+
+The version number follows the SDKs (`3.x`, `lib/i18n_keyless/version.rb`, written by
+`scripts/set-version.mjs`).
+
+## Development
+
+```bash
+cd ports/rails
+bundle install
+bundle exec rake test
+```
+
+Tests run on minitest with WebMock: no network, no key. `test/conformance/vectors_test.rb`
+replays the monorepo's shared protocol vectors (`conformance/vectors/*.json`): language
+codes, locale resolution, storage key, namespace resolution, retry decisions, backoff
+scenarios, dictionary and translate requests and responses, usage requests. The test is
+skipped when the vectors directory is absent (standalone checkout).
+`test/integration/railtie_test.rb` boots a one-file Rails application and drives a request
+through the middleware.
+
+One deliberate difference from the JavaScript SDKs: misses are deduplicated by key AND
+context (the SDK queue ignores the context). Usage analytics follow the node SDK
+(`sdk: rails` is a server label with the `node` rules).

data/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: i18n-keyless-rails
+description: Install and use i18n-keyless in a Ruby on Rails application. t('Welcome to our app') (the source string where a key would go) resolves through the i18n-keyless API with one gem and two .env lines. Use when adding, configuring or debugging translations / localization / multi-language support in a Rails 7 or 8 project, or when the project already depends on `i18n-keyless-rails`.
+license: MIT
+---
+
+# i18n-keyless for Ruby on Rails
+
+Rails' `t()` takes a key and looks it up in `config/locales/*.yml`. This gem chains an I18n
+backend after the application's: a `t('Welcome to our app')` call whose argument is a source
+string, not a key, is translated by AI once, for every language, cached in `Rails.cache`,
+and served from there. No YAML to maintain for those strings.
+
+**Version covered: `i18n-keyless-rails` 3.x, Rails 7.0 to 8.x, Ruby >= 3.1.**
+
+## Install in one step
+
+```bash
+bundle add i18n-keyless-rails
+```
+
+```dotenv
+I18N_KEYLESS_API_KEY=...            # required: https://i18n-keyless.com/#get-api-key
+I18N_KEYLESS_LANGUAGES=en,fr,es     # required for translation: every language the app serves
+I18N_KEYLESS_PRIMARY_LANG=en        # the language the source strings are written in (default: I18n.default_locale)
+```
+
+The Railtie is auto-loaded. No code change: `t()`, `I18n.t`, `translate()` keep their
+signatures; the `i18nk` helper is mixed into views, controllers, mailers and jobs.
+
+## Rules
+
+- Source strings are written in the primary language. `t('Bonjour')` in a French-first app,
+  `t('Hello')` in an English-first one. Never invent a key name for a keyless string.
+- What is a Rails key, left to YAML and never sent: a Symbol (`t(:hello)`), a `scope:`, a
+  lazy lookup (`t('.title')`), or a lowercase identifier path (`t('hello')`,
+  `t('users.index.title')`). What is a source string: anything with a space, an uppercase
+  letter or punctuation. For a lowercase one-word source string, use `i18nk('close')`.
+  The rule is `config.rails_key_pattern`.
+- Placeholders are I18n's: `t('Bienvenue %{name}', name: name)`. Do not use the SDKs'
+  `replace` option or `{{name}}` syntax.
+- Ambiguous strings take a context: `t('8 heures', context: 'duration')` or
+  `i18nk('8 heures', context: 'duration')`. Stored as `8 heures__duration`, the same entry
+  the other SDKs use. `namespace:` travels the same way.
+- Plurals: YAML `one:` / `other:` rules do not apply to a source string. Use one `i18nk()`
+  per form with a `context`, or a YAML file.
+- The current locale is `I18n.locale`. Switching it (`I18n.locale = :fr`, `around_action`,
+  `?locale=`) is all that is needed; the gem loads the locale on its first miss. Rails
+  locales are mapped: `pt_BR` is `pt-BR`, `zh_CN` is `zh-Hans`. List the served locales in
+  `config.i18n.available_locales` when they have no YAML file.
+- Always set `I18N_KEYLESS_LANGUAGES` to the full list the app serves. It is what a new
+  string is translated into, and the API stores it as the project's language list (it
+  replaces the previous one). Without it, missing strings are never sent: they stay as
+  source text and one warning `I18N_KEYLESS_LANGUAGES is required` is logged per process.
+- Nothing blocks a request except the very first fetch of a language's dictionary. Misses
+  are sent after the response (a Rack middleware) or, with `I18N_KEYLESS_QUEUE=<queue>`, as
+  an `I18nKeyless::TranslateMissingKeysJob`.
+- Never raises. A failed API call shows the source text and is retried at the next request.
+- Every request carries `Authorization: Bearer`, `Version: 3.5.0` and `sdk: rails` (a
+  server label: counted by connection, no device id, usage analytics like the node SDK).
+- A line in `config/locales/{locale}.yml` wins over the API. Delete it to let the API serve it.
+- Usage analytics are on by default, like the node SDK: one `POST
+  /translate/last-used-translations` at most every 10 s, after the response, never blocking.
+  `I18N_KEYLESS_USAGE=false` turns them off.
+- Use a shared cache store in production (Redis, Memcached, the database): the miss guard
+  and the usage lock live in `Rails.cache`, and a `:memory_store` is per process.
+- If the app sets `I18n.backend` itself after boot, chain again with `I18nKeyless.install!`.
+- A source string is capped at 2000 characters (`context` and `namespace` at 200). Long-form
+  content is allowed, but a blog post is one translation **per Markdown block** of about 1000
+  characters: keep the Markdown inside each block, give every block of the document the same
+  `context` — one very short summary of it — and one `namespace` per document.
+  https://docs.i18n-keyless.com/docs/guides/long-form-content
+
+## Configuration
+
+`I18nKeyless.configure { |c| ... }` in an initializer, or the environment. Keys: `enabled`,
+`api_key`, `api_url`, `primary`, `languages`, `namespace`, `cache`, `cache_ttl`,
+`cache_prefix`, `timeout` (10 s), `retry` (`[500, 1500]` ms), `concurrency` (30), `usage`
+(true), `queue`, `logger`, `rails_key_pattern`.
+Env: `I18N_KEYLESS_ENABLED`, `I18N_KEYLESS_API_KEY`, `I18N_KEYLESS_API_URL`,
+`I18N_KEYLESS_PRIMARY_LANG`, `I18N_KEYLESS_LANGUAGES`, `I18N_KEYLESS_NAMESPACE`,
+`I18N_KEYLESS_CACHE_TTL`, `I18N_KEYLESS_USAGE`, `I18N_KEYLESS_QUEUE`.
+
+## Debug
+
+- `t()` returns the source text in a non-primary locale: check `I18N_KEYLESS_API_KEY` and
+  `I18N_KEYLESS_LANGUAGES`, that the locale maps to a supported code and is in the list, and
+  the log for lines starting with `i18n-keyless:`.
+- `t()` returns `Translation missing`: the argument matched the Rails-key rule (lowercase
+  identifier). Use `i18nk()` or capitalise the source string.
+- A translation does not update after a dashboard edit: the dictionary is served for
+  `cache_ttl` seconds before revalidation. `Rails.cache.clear` forces a refetch.
+- A string is POSTed on every request: the miss guard lives in the cache; make sure the
+  cache store is shared between processes (not `:memory_store` or `:null_store`).
+
+## Offline try-out
+
+Run `examples/_mock-server` (`node server.mjs`, port 8787) and set
+`I18N_KEYLESS_API_URL=http://localhost:8787`, `I18N_KEYLESS_API_KEY=demo`,
+`I18N_KEYLESS_PRIMARY_LANG=fr`. See `examples/rails/README.md`.
+
+## Go deeper
+
+- Gem README: `ports/rails/README.md`
+- The whole i18n-keyless documentation as one file: https://docs.i18n-keyless.com/llms.txt
+- Dashboard: https://i18n-keyless.com/dashboard

data/lib/i18n-keyless-rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# `require "i18n-keyless-rails"` (the gem name) and `require "i18n_keyless"` are the same thing.
+require_relative "i18n_keyless"