senren-ui 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c822ae4c548e611bba93a0ffd7654a881b4626173e3a85898e8221318aca6f2e
-  data.tar.gz: 48b9d43cf61a38d652f5e993e5baff8d5bff3514b381ee4eeafce95dad7f1113
+  metadata.gz: 99b7430e710e44023cbc886c862b4d237d06bb489a4a00f5e30685b59768f6dc
+  data.tar.gz: 6ead04eac8e4e518cbf7129c65dfb63ad683db3dfb44b13a794366eee8be37dd
 SHA512:
-  metadata.gz: cb02d352ef3be737cc00be01c8178874d6b9409c7e54da22917d2d6c4dbe1be0e3baa948bfabce77e5f18241284097bd254b520845ab71b5d1d4d01f573d4e64
-  data.tar.gz: edcb1633812058eba68a7014f7239cddf4df698dccc8371c3d968c73e6cbd0913453d7fb9fee00e791e12e4c1080a9b31f1c1db76b3ac42b069606975d07d684
+  metadata.gz: 7cf42a8f5992b7de9bc4135c7d6bea7c44987ca3844de06b575876957877efd773711cdfcb9cd54d2ddc1ca878f38842d4df082b0fb7451b5b63613c9bb5f056
+  data.tar.gz: e3c329bc7eb8ef0c7b90af18971c92f24dfdea4822e17a9e43faff3b1e94a6815ed4b6c18cff30a2e65932cd8bf96d88b2e64153671d72e2a52c8ffe2d759c76

data/CHANGELOG.md

@@ -7,6 +7,133 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 v0.x is a pre-stable line: minor bumps may break things; patch bumps are
 bug fixes only.
 
+## [0.4.0] — 2026-10-08
+
+### Added
+
+- **Every word a component shows or announces can be translated from the host
+  app, without editing a component.** Visible text, `aria-label` and `sr-only`
+  text, the defaults of `label:`, `placeholder:` and `empty_text:`, the
+  calendar's month and weekday names, and the sentences a Stimulus controller
+  says after load now go through one helper, `senren_t`, with the English as its
+  default: `senren_t('pagination.next', default: 'Next')` is
+  `I18n.t("senren.pagination.next", default: "Next")`. 111 keys across 27
+  components, named `senren.<component>.<key>`, with `senren.shared.*` for the
+  two words that are the same word in several components.
+
+  An app with no locale file renders exactly what it did before, and a missing
+  translation never raises, including under
+  `config.i18n.raise_on_missing_translations`. Text you pass in yourself is used
+  as given and never looked up; `label: nil` still means "none", and leaving the
+  argument out is what gets the translated default.
+
+  The gem ships `senren.en.yml` and `senren.vi.yml`, and copies either only
+  when asked for: `bin/rails generate senren:install --locales vi`, or later
+  `bin/rails senren:locales vi`. Not even English is copied by default: a copied
+  `senren.en.yml` loads after the app's `en.yml`, overriding any `senren.*` key
+  set there, and pins today's wording against later releases. An existing file
+  is never overwritten unless that is asked for by name
+  (`senren:locales vi --force`, or `senren:install --force-locales`); the
+  `--force` that refreshes Senren's own files leaves translations alone. To add
+  another language, `bin/rails senren:locales en`, copy the file, change `en:`,
+  and translate the values. A translation with a misspelt `%{variable}` falls
+  back to the English instead of raising. See [docs/i18n.md](docs/i18n.md).
+
+  `bin/i18n-sync` regenerates `templates/locales/senren.en.yml` from the code,
+  and a test fails if it, `senren.vi.yml`, and the components disagree, or if a
+  template shows a word that did not go through `senren_t`.
+
+### Changed
+
+- **Five Stimulus controllers no longer carry an English sentence.** `clipboard`
+  ("Copied", "Copied to clipboard"), `api_key_field` ("Copy complete"),
+  `carousel` ("Slide 2 of 3"), `theme_toggle` ("Light theme", "Dark theme") and
+  `rich_text_editor_lite` (the link prompt) read the sentence from a Stimulus
+  value the component renders, so they speak the host's language. The markup
+  gains six `data-senren--<controller>-…-value` attributes and is otherwise
+  byte-for-byte what it was.
+
+  **Migrate:** none for an unmodified install. The controller and its component
+  go together: if you copied a component and edited its controller, or the other
+  way round, copy both again (`bin/rails senren:add <name> --force`) so the value
+  the controller reads is the one the component writes.
+- `bin/rails senren:add` appends `senren_t` to an existing
+  `app/components/senren/base_component.rb` that lacks it, so a component added
+  after upgrading the gem does not raise `NoMethodError`. Components you copied
+  earlier keep the English written into them until you copy them again.
+- The performance budgets for component source (140000 -> 150000 bytes) and for
+  the Stimulus payload (56000 -> 56500) are raised, with the reasons recorded in
+  `config/performance_budgets.yml`. The per-file caps and the gzip total are
+  unchanged.
+- **`NativeSelectComponent` defaults to its own chevron instead of the browser's
+  arrow** (`native_arrow: false`). A select was the one control in the library
+  with no visible state: the OS arrow cannot be styled or animated, so nothing
+  distinguished an open select from a closed one. The custom chevron already
+  existed, rotated on focus, and had to be asked for by name — which meant
+  nobody got it. Pass `native_arrow: true` to opt back in; worth doing on
+  mobile, where the OS renders its own picker anyway.
+
+  The component marker moves with it. In custom-arrow mode
+  `data-senren-component="native_select"` sits on the wrapper that positions the
+  chevron, and the `<select>` underneath still carries the name, the controller
+  and the selection. Anything selecting on `select[data-senren-component]` needs
+  updating.
+- `InviteMemberDialogComponent` renders its role field through
+  `NativeSelectComponent` rather than a hand-written `<select>` whose styling
+  had been copied out of it — which is why it silently missed everything that
+  component gained afterwards, the chevron included.
+
+### Fixed
+
+- `FormComponent` yields the Rails form builder, as `docs/components.md` always
+  said it did. The block received the component instead, and because a
+  component is an `ActionView::Base` the documented `f.text_field :title,
+  class: "x"` did not raise: it reached the template-level helper and rendered
+  `name="title[{class: "x"}]"`, so the field posted under a name no controller
+  reads. Blocks that never touch `f`, and `with_content`, render as before.
+
+  Code that treated `|f|` as the component breaks: `f.tag`, `f.link_to`,
+  `f.render`, `f.model` and `f.url` now raise `NoMethodError` on the builder.
+  Call those on the view instead. A `FormComponent` rendered with neither a
+  block nor content now renders an empty `<form>` rather than raising.
+- `TopNavComponent`'s default variant had no background. Its class,
+  `bg-[hsl(var(--senren-background))/0.88]`, put the alpha outside `hsl()`,
+  inside the brackets, so Tailwind emitted `hsl(...)/0.88` verbatim and the
+  browser dropped it as an invalid colour: the sticky header was transparent
+  over scrolled content. It is now `bg-[hsl(var(--senren-background)/0.88)]`,
+  the form every other translucent class in the library uses, and a test bans
+  the broken shape across `templates/` and `lib/`.
+- `TableComponent` and `DataTableComponent` are now `relative`, so their
+  `sr-only` caption is positioned inside the component. `sr-only` is
+  `position: absolute`, and with nothing positioned the caption escaped the
+  components' own overflow clipping and was placed against the page. In a
+  fixed-height shell whose `<main>` scrolls, a captioned table below the fold
+  made the document taller, and the window scrolled into blank space under a
+  shell that should never scroll.
+- `DataTableComponent` no longer breaks a `<td>` whose cell holds markup. The
+  cell value was written straight into `data-sort-value="..."`, and a badge,
+  link or anything else built with `tag` or `render` is a SafeBuffer, which ERB
+  does not escape: the markup's first `"` closed the attribute, the rest became
+  junk attributes, and every row sorted on the same `<span class=` fragment.
+  The sort value is now the cell's decoded text, escaped once, so a cell
+  showing `R&D` sorts as `R&D`. Plain-string and numeric cells are unchanged.
+- `ThemeToggleComponent` rendered the letters `O`, `D` and `L` where an icon
+  belongs. It now ships sun and moon SVGs and swaps which is hidden, so the
+  correct icon is in the HTML the server sends rather than written in by
+  JavaScript after first paint. The icon names the theme the click switches to,
+  matching the label.
+- `AccordionComponent` showed a static `+` and snapped open. It now has a
+  chevron that turns over, driven by `aria-expanded` so the icon cannot drift
+  out of step with the state assistive technology is told, and the panel
+  animates via `grid-template-rows: 0fr → 1fr` — which reaches the content's own
+  height without measuring it in JavaScript.
+
+  The `hidden` attribute is kept through the animation. Content that is visually
+  collapsed but present is still focusable and still read aloud, so the
+  controller drops `hidden` before opening and restores it once the closing
+  transition ends, with a timer for the cases where `transitionend` never
+  arrives: reduced motion, an off-screen element, an already-collapsed panel.
+
 ## [0.3.0] — 2026-09-01
 
 ### Breaking

data/CONTRIBUTING.md

@@ -36,6 +36,7 @@ bundle exec rubocop
 bundle exec bundle-audit check --update
 bun run controllers:check
 bin/lint-fix                          # auto-fix RuboCop, ERB lint, controller JS
+bin/i18n-sync --check                 # templates/locales/senren.en.yml matches the components
 ```
 
 `bin/system` needs no setup: it uses a system Chrome and
@@ -87,6 +88,13 @@ real documentation/reference app is maintained separately in
 - ViewComponent Ruby class under `Senren::` namespace.
 - ERB template with `data-senren-component="<name>"` on root.
 - Tailwind classes use semantic tokens only.
+- Every word the component shows or announces (visible text, `aria-label`,
+  `sr-only`, a default `label:` or `placeholder:`, a sentence a controller will
+  say) goes through `senren_t('<component>.<key>', default: 'English')` with a
+  literal key and a literal default, and a controller receives it as a Stimulus
+  value, never as text in JavaScript. Run `bin/i18n-sync` to regenerate
+  `templates/locales/senren.en.yml` and add the same key to `senren.vi.yml`.
+  See `docs/i18n.md`.
 - Variants/sizes declared as class-level constants.
 - Stimulus controller iff client behavior is needed
   (`app/javascript/controllers/senren/<name>_controller.js`).
@@ -115,6 +123,8 @@ real documentation/reference app is maintained separately in
   templates, Stimulus controllers, or Importmap loading guidance.
 - Run `bun run controllers:check` before pushing if you touched
   `templates/controllers/*.js`.
+- Run `bin/i18n-sync --check` before pushing if you touched text in a
+  component; `bin/i18n-sync` fixes what it reports.
 
 ## Pull request workflow
 

data/README.md

@@ -80,6 +80,40 @@ change, no build step, no configuration. Switch at runtime with
 
 Details and the token table: [docs/visual_style.md](docs/visual_style.md).
 
+## Translating components
+
+Every word a component shows or announces (labels, `aria-label` and
+screen-reader text, default placeholders, the calendar's month and weekday names,
+and what a Stimulus controller says after load) goes through one helper with its
+English as the default:
+
+```ruby
+senren_t('pagination.next', default: 'Next')   # I18n.t("senren.pagination.next", default: "Next")
+```
+
+An app with no locale file renders exactly the English it always did, and the
+installer copies none unless asked. To change a word, set its `senren.*` key in
+your own locale file. To add a language, copy a shipped file and translate it:
+
+```bash
+bin/rails generate senren:install --locales vi   # writes config/locales/senren.vi.yml
+bin/rails senren:locales en                      # every key and its English, to translate from
+```
+
+```yaml
+# config/locales/senren.fr.yml - copy senren.en.yml, change `en:` to `fr:`, translate the values
+fr:
+  senren:
+    pagination:
+      previous: "Précédent"
+      next: "Suivant"
+```
+
+The gem ships `en` and `vi`. A key you leave out stays English, and a missing
+key never raises. [docs/i18n.md](docs/i18n.md) has the key naming, the values a
+controller reads, what is not translated, and how to move components you copied
+before this existed.
+
 ## Daily commands
 
 ```bash
@@ -88,6 +122,7 @@ bin/rails generate senren:component picker --client  # custom component with Sti
 bin/rails generate senren:component picker --no-client  # without Stimulus
 bin/rails senren:add dialog --client        # install interactive official component
 bin/rails senren:add button                 # install static official component
+bin/rails senren:locales vi                 # copy a shipped translation to config/locales
 bundle exec rails senren:add form input     # equivalent alternate entry point
 bin/rails senren:skill:sync                 # rebuild .senren/skill.md
 bin/rails senren:agents:sync                # rebuild .senren/agent-rules + adapters
@@ -263,6 +298,7 @@ bun run controllers:check        # lint + syntax check for templates/controllers
 bun run controllers:lint:fix     # auto-fix lint issues for controllers
 bundle exec rake test:system     # Stimulus/system tests
 bin/lint-fix                     # auto-fix RuboCop, ERB lint, and controller JS
+bin/i18n-sync                    # rewrite templates/locales/senren.en.yml from the senren_t calls
 ```
 
 ## Contributing

data/docs/i18n.md

@@ -0,0 +1,194 @@
+# Translating Senren components
+
+Every word a component shows or announces can be translated from your app's
+locale files, without editing a component. That covers the visible labels
+("Previous", "Next", "Close", "Today"), the `aria-label` and screen-reader text
+("Toggle sidebar", "Go to slide 2"), the defaults for arguments such as
+`label:` and `placeholder:`, the calendar's month and weekday names, and the
+sentences a Stimulus controller writes into the page after it loads ("Copied",
+"Slide 2 of 3").
+
+## How it works
+
+Each string goes through one helper, `senren_t`, with its English as the
+default:
+
+```ruby
+senren_t('pagination.next', default: 'Next')
+```
+
+That is `I18n.t("senren.pagination.next", default: "Next")`. If your app defines
+`senren.pagination.next` for the current locale it wins; if not, the English in
+the component is used. Two things follow:
+
+- **Nothing is required for English.** Install Senren, render a component, and it
+  says what it always said. There is no locale file to forget.
+- **A missing translation never raises**, not even with
+  `config.i18n.raise_on_missing_translations = true`, because I18n only reports
+  a key that has no default.
+
+Keys are `senren.<component>.<key>`. `senren.shared.*` holds the few words that
+are the same word in more than one component (`open`, `close`).
+
+## Install the locale files
+
+`senren:install` copies no locale file: English needs none. Every file is
+copied only when you ask for it by name:
+
+```bash
+bin/rails generate senren:install --locales vi   # at install time
+bin/rails senren:locales vi                      # any time later
+bin/rails senren:locales en                      # every key and its English, to translate from
+bin/rails senren:locales vi --force              # replace your copy with the shipped one
+```
+
+Today the gem ships `en` and `vi`. The files are yours once they are copied:
+the installer never overwrites one that exists unless you ask for that file to
+be replaced (`senren:locales <name> --force`, or `--force-locales` on
+`senren:install`). The `--force` that refreshes Senren's own files leaves them
+alone, so a re-run after a gem upgrade does not undo your wording.
+
+A copied `senren.en.yml` has two side effects, which is why it is not copied by
+default. Rails loads `config/locales` in name order, so it loads after your
+`en.yml` and overrides any `senren.*` key you set there. And it pins today's
+English: when a later Senren release improves a default, an app holding the copy
+keeps the old wording. Copy it to translate from, and delete it once your own
+language file exists.
+
+A translation is only loaded when its file is in `config/locales`, and a locale
+becomes known to I18n when a file for it is loaded. If your app builds a
+language switcher from `I18n.available_locales`, copying `senren.vi.yml` is what
+makes Vietnamese appear in it, which is why it is opt-in.
+
+## Change one word
+
+Define just that key in any locale file you already have. You do not need to
+copy the whole file:
+
+```yaml
+# config/locales/en.yml
+en:
+  senren:
+    pagination:
+      next: "Newer"
+      previous: "Older"
+```
+
+Everything you do not mention keeps its English. If you copied
+`config/locales/senren.en.yml`, edit the value there instead: that file loads
+after `en.yml` and wins.
+
+## Add a language
+
+1. Run `bin/rails senren:locales en`, then copy `config/locales/senren.en.yml` to
+   `config/locales/senren.fr.yml`.
+2. Change the top-level key from `en:` to `fr:`.
+3. Translate the values.
+
+```yaml
+fr:
+  senren:
+    pagination:
+      label: "Pagination"
+      previous: "Précédent"
+      next: "Suivant"
+    cart:
+      remove_item: "Retirer %{name}"
+```
+
+Keep every `%{name}` spelled exactly as it is. They are filled in when the
+component renders. A translation that names a variable the component does not
+pass (a typo such as `%{nmae}`) cannot be filled in, so that string falls back to
+its English rather than raising. You can
+move a variable anywhere in the sentence, and leave one out if the sentence does
+not need it. A key you delete falls back to English, so a partial translation is
+a working translation.
+
+Then select the locale the way your app already does, for example
+`I18n.locale = :fr` in an `around_action`. A word you did not translate shows in
+English, because the English is the default.
+
+If you would like the language included in the gem, send the file in a pull
+request: `templates/locales/senren.<locale>.yml`, with the same keys as
+`senren.en.yml`. `test/i18n_catalog_test.rb` checks that the keys and the
+`%{}` variables match.
+
+## Text you pass in yourself
+
+An argument you pass is used exactly as given and is never looked up:
+
+```erb
+<%= render Senren::PaginationComponent.new(label: "Pages", current_page: 2, total_pages: 5) %>
+```
+
+Only the argument you leave out gets the translated default. Two details:
+
+- `label: nil` still means "no label". For an attribute such as `aria-label` that
+  omits it, as it always has. Pass `""` for an empty string and leave the
+  argument out for the default.
+- Words that arrive as *data* are yours to supply: a column header built from the
+  key `:created_at` ("Created at"), the items of a menu, the text in a slot. Give
+  `TableComponent` and `DataTableComponent` a `label:` per column to control it.
+
+Values you interpolate into a translation are text. A name containing `<b>`
+shows as the characters `<b>`, not as an element.
+
+## What a controller says
+
+Five controllers write a sentence into the page after it loads. They no longer
+carry the English in JavaScript: the component renders each one into a Stimulus
+value, and the controller reads it.
+
+| Controller | Value | Key |
+| --- | --- | --- |
+| `clipboard` | `copied-status` | `senren.clipboard.copied_status` |
+| `api_key_field` | `copied-status` | `senren.api_key_field.copied_status` |
+| `carousel` | `status-template` | `senren.carousel.status` |
+| `theme_toggle` | `light-label`, `dark-label` | `senren.theme_toggle.light`, `.dark` |
+| `rich_text_editor_lite` | `link-prompt` | `senren.rich_text_editor_lite.link_prompt` |
+
+The carousel's value is a template. Its `%{current}` and `%{total}` are left in
+for the controller to fill in on every slide change, so a translation has to keep
+them.
+
+## Components you copied before this existed
+
+`bin/rails senren:add <anything>` adds the `senren_t` helper to your
+`app/components/senren/base_component.rb` if it is missing, so components you add
+from now on work.
+
+Components you copied earlier still have their English written into them. To
+translate one, copy it again with `bin/rails senren:add pagination --force`
+(which replaces any edits you made to that component), or change its strings by
+hand. It is one call per string: swap `"Next"` for
+`senren_t('pagination.next', default: 'Next')`. `senren.en.yml` lists the key for
+every string.
+
+## Writing a component or an edit that has text
+
+Anything a person reads or a screen reader announces goes through `senren_t`
+with a literal key and a literal English default:
+
+```ruby
+def initialize(label: senren_t('tabs.label', default: 'Tabs'), **html)
+```
+
+```erb
+<button><%= senren_t('date_picker.today', default: 'Today') %></button>
+<button aria-label="<%= senren_t('cart.remove_item', default: 'Remove %{name}', name: item[:name]) %>">
+```
+
+- Use the component's own namespace. Use `shared` only for a word that more than
+  one component says.
+- Put the English where the call is. Do not write it in a locale file first.
+- Give an argument its default in the signature, as above. Ruby evaluates it
+  when the component is built, in the locale that is current then.
+- A string a controller needs goes to it as a Stimulus value, never as text in the
+  JavaScript.
+- Symbols that are not words (`×`, `+`, `*`) stay as they are.
+
+If you are working on the gem itself, `bin/i18n-sync` regenerates
+`templates/locales/senren.en.yml` from the calls, and `bin/i18n-sync --check`
+reports whether it is current. `senren.vi.yml` is written by hand. The tests fail
+if the two files disagree with the code or with each other, if a call is not
+literal, and if a template shows a word that did not go through `senren_t`.

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

@@ -11,6 +11,24 @@ module Senren
       class_option :force, type: :boolean, default: false,
                            desc: 'Overwrite existing Senren-managed files.'
 
+      # Nothing by default: English renders with no file. Every locale, English
+      # included, is asked for by name. A shipped translation adds its locale to
+      # I18n.available_locales, which a language switcher built from that list
+      # will then offer; a copied English file overrides the app's own en.yml.
+      #
+      # `enum:` makes Thor refuse an unknown locale while it parses the options,
+      # before any step has run. Refusing in the middle would leave an app with the
+      # components copied and no instruction files.
+      class_option :locales, type: :array, default: [],
+                             enum: Senren::Rails::LocaleInstaller.available,
+                             desc: 'Translations to copy into config/locales.'
+
+      # --force refreshes the files Senren owns. A locale file stops being one
+      # the moment it is copied: it is the app's translation. So replacing it is
+      # its own flag, and a routine --force re-run cannot undo someone's wording.
+      class_option :force_locales, type: :boolean, default: false,
+                                   desc: 'Replace locale files that already exist with the shipped ones.'
+
       def create_senren_dir
         empty_directory '.senren'
       end
@@ -41,6 +59,23 @@ module Senren
         copy_file Senren::Rails.registry_path, '.senren/registry.yml'
       end
 
+      # Components work without these: the English is in the code. Nothing is
+      # copied unless asked for, English included -- a copied senren.en.yml would
+      # override the app's own en.yml and pin today's wording (see
+      # LocaleInstaller). An existing file is a translation someone wrote, so it
+      # is kept unless --force-locales is given.
+      def copy_locale_files
+        locales = options[:locales]
+        if locales.empty?
+          say_status :senren, 'no locale files copied: English needs none (bin/rails senren:locales vi to add one)'
+          return
+        end
+
+        say_status :senren, "copying locale files (#{locales.join(', ')}) to config/locales"
+        installer = Senren::Rails::LocaleInstaller.new(paths: host_paths)
+        installer.install(locales: locales, force: options[:force_locales])
+      end
+
       # Switches Stimulus to on-demand loading instead of documenting it.
       #
       # Rails' default is `eagerLoadControllersFrom("controllers", application)`,
@@ -75,6 +110,7 @@ module Senren
       def print_next_steps
         say "\nSenren installed."
         say 'Next: bin/rails senren:add button card badge alert dialog'
+        say 'Translate the components: bin/rails senren:locales vi (see docs/i18n.md)'
         say 'Then: bin/rails senren:agents:sync'
       end
 

data/lib/generators/senren/install/templates/base_component.rb.tt

@@ -1,4 +1,5 @@
 require 'uri'
+require 'active_support/i18n'
 require 'view_component'
 
 module Senren
@@ -105,6 +106,44 @@ module Senren
       "#{base}-#{seed.parameterize}"
     end
 
+    # Translates a string the component shows or announces: a visible label, an
+    # aria-label, sr-only text, a default placeholder, an announcement a Stimulus
+    # controller will read out.
+    #
+    #   senren_t('pagination.next', default: 'Next')
+    #   senren_t('cart.remove_item', default: 'Remove %{name}', name: item[:name])
+    #
+    # `default:` is the English text and it is required. It is what renders when
+    # the host app has no `senren.<key>` translation, which is why installing
+    # Senren needs no locale file, why a key nobody translated never raises (not
+    # even under `config.i18n.raise_on_missing_translations`, which only fires
+    # for a key with no default), and why the output is the same as it was before
+    # any string was translatable.
+    #
+    # This is I18n.t on purpose, not ViewComponent's `t`. `t` needs a view
+    # context, so it cannot run in a unit test that renders a template without
+    # Rails; it resolves a leading-dot key against the component's own sidecar
+    # scope, which is the lookup this namespace must not have; and it marks keys
+    # ending in `_html` as safe, which no Senren string is.
+    #
+    # Keys are `senren.<component>.<key>`; `senren.shared.<key>` is for a word
+    # that is the same word in more than one component. Interpolate with `%{}`.
+    # With no values passed the raw template comes back untouched, which is how a
+    # Stimulus controller is handed a string it fills in itself.
+    #
+    # A translation that names a variable the call does not pass (`%{nmae}`
+    # for `%{name}`) would raise I18n::MissingInterpolationArgument and turn a
+    # typo in a locale file into a 500. It falls back to the English instead,
+    # interpolated with the values the call did pass.
+    #
+    # Public, because the unit tests that render a template without a view
+    # delegate every public component method to it.
+    def senren_t(key, default:, **options)
+      I18n.t("senren.#{key}", default: default, **options)
+    rescue I18n::MissingInterpolationArgument
+      I18n.interpolate(default, options)
+    end
+
     private
 
     # Callers write `data: { controller: "x" }` and `data: { "controller" => "x" }`

data/lib/generators/senren/install/templates/conventions.md.tt

@@ -83,6 +83,22 @@ and obey it strictly.
     ```
     Classes from families the component does not use need no modifier.
 
+12. **Every word a component shows or announces goes through `senren_t`.**
+    Visible text, `aria-label`, `sr-only` text, a default `label:` or
+    `placeholder:`, and any sentence a Stimulus controller will say. The English
+    is the `default:`, the key is `<component>.<key>`, and both are literals:
+    ```ruby
+    senren_t('pagination.next', default: 'Next')
+    senren_t('cart.remove_item', default: 'Remove %{name}', name: item[:name])
+    def initialize(label: senren_t('tabs.label', default: 'Tabs'), **html)
+    ```
+    Never hard-code a sentence in a template, and never write one in a Stimulus
+    controller: hand the controller a translated string as a value. An app with
+    no locale file renders the English unchanged; to change a word, set its
+    `senren.*` key in a locale file, and to add a language, start from
+    `bin/rails senren:locales en` (`bin/rails senren:locales vi` installs a
+    shipped translation).
+
 ## File ownership
 
 | Path                                | Owned by         |

data/lib/senren/rails/agent_rules_writer.rb

@@ -109,6 +109,10 @@ module Senren
           - A button inside a form needs no `type:`. ButtonComponent omits the
             attribute so the browser submits, as plain HTML does. Pass
             `type: :button` only for a trigger that must not submit.
+          - Text a component shows or announces goes through
+            `senren_t('<component>.<key>', default: 'English')`, with a literal key
+            and default. Never hard-code a sentence in a template or in a Stimulus
+            controller; hand the controller a translated string as a value.
 
           ## Important Files
 

data/lib/senren/rails/base_component_patch.rb

@@ -59,6 +59,30 @@ module Senren
           end
         end
       RUBY
+
+      # Ruby appended to a host app's existing BaseComponent when it predates
+      # senren_t. A component copied by `senren:add` calls it, so without this a
+      # host that upgraded the gem and added one component would get a
+      # NoMethodError the first time that component rendered.
+      #
+      # Same arrangement as URL_HELPERS: apps installed earlier never receive the
+      # template again, so the helper is duplicated here, and
+      # test/i18n_catalog_test.rb pins the two bodies together.
+      TRANSLATION_HELPER = <<~'RUBY'
+
+        # Added by senren:add so components that translate their text can render.
+        require 'active_support/i18n'
+
+        module Senren
+          class BaseComponent
+            def senren_t(key, default:, **options)
+              I18n.t("senren.#{key}", default: default, **options)
+            rescue I18n::MissingInterpolationArgument
+              I18n.interpolate(default, options)
+            end
+          end
+        end
+      RUBY
     end
   end
 end

data/lib/senren/rails/component_copier.rb

@@ -19,6 +19,7 @@ module Senren
       ).freeze
       BASE_COMPONENT_TEMPLATE = File.join(INSTALL_GENERATOR_TEMPLATES, 'base_component.rb.tt').freeze
       BASE_URL_HELPER_PATCH = BaseComponentPatch::URL_HELPERS
+      BASE_TRANSLATION_HELPER_PATCH = BaseComponentPatch::TRANSLATION_HELPER
 
       attr_reader :registry, :paths, :stdout
 
@@ -35,6 +36,7 @@ module Senren
         validate_client_override!(component_names, client_override)
         paths.ensure_dirs!
         ensure_base_component_url_helpers!
+        ensure_base_component_translation_helper!
 
         requested = Array(component_names).map(&:to_s)
         wanted.each do |name|
@@ -85,6 +87,25 @@ module Senren
         copy_file(BASE_COMPONENT_TEMPLATE, dest, force: false, label: 'base_component.rb')
       end
 
+      # A component that translates its text calls senren_t, so a host whose
+      # BaseComponent predates it needs the helper before the component renders.
+      # Runs after the URL helper step, which copies the whole current template
+      # (helper included) when there is no base component at all, so in that
+      # case there is nothing left to add.
+      #
+      # A destination that escapes the app root was already reported by the URL
+      # step, so this one declines without saying it a second time.
+      def ensure_base_component_translation_helper!
+        dest = paths.base_component_path
+
+        return unless SafeWrite.inside?(dest, paths.root)
+        return unless dest.exist?
+        return if dest.read.include?('def senren_t')
+
+        SafeWrite.write!(dest, dest.read + BASE_TRANSLATION_HELPER_PATCH, paths.root, 'base_component.rb')
+        stdout.puts "  update #{dest} (senren_t)"
+      end
+
       # Delegates to SafeWrite so an intermediate symlinked directory is caught,
       # not just a symlinked leaf. `app/components/senren -> /elsewhere` used to
       # pass every check here.

data/lib/senren/rails/host_paths.rb

@@ -24,6 +24,11 @@ module Senren
 
       def stylesheet_path       = root.join('app', 'assets', 'stylesheets', 'senren.css')
 
+      # Where the host's translations of component text live. One file per
+      # locale, so a team adds a language by adding a file.
+      def locales_dir           = root.join('config', 'locales')
+      def locale_file(locale)   = locales_dir.join("senren.#{locale}.yml")
+
       def stimulus_dir          = root.join('app', 'javascript', 'controllers', 'senren')
 
       def github_dir            = root.join('.github')