Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Localized user-text lint guard (#2618)
Change contract
Production ui/src/**/*.tsx JSX children and aria-label, title,
placeholder, and alt must not contain literal copy or literal sentence/list
composition. Locale templates, Trans component interpolation, and locale-aware
formatters own composition. No UI copy or locale resource is changed in this
rollout.
Use one dependency-free custom ESLint rule with the installed TypeScript AST and
ESLint lexical scopes. Follow immutable local bindings, TypeScript wrappers,
conditional display branches, arrays, and inline map/filter result paths into
these sinks. Calls to translation/formatting functions remain value boundaries;
this is not whole-program taint analysis. In particular, the original accessible
label used component props, not inline t() calls: literal joins at a sink must
be diagnosed even when the dynamic values' provenance is unknown.
Keep the rule pinned at error in the shared policy for every TS/TSX file; decide its narrower production-TSX applicability inside the rule. Preserve domain, policy, inline-override and suppression verification without exemptions there.
Allow/deny boundaries
- Deny ordinary literal JSX copy and punctuation, string templates/
+/.joinwith literal glue reaching the listed sinks, including local const aliases. - Permit dynamic data, translation/formatter results, locale-owned separators,
and genuine
react-i18nextTransinterpolation. Do not examine class names, protocol props, logging, translation keys, or arbitrary call arguments as copy. - Decorative exemptions must be explicit, direct, and glyph-only. Separators
such as the original
aria-hiddenmiddle dot are not decorative opt-outs. - Technical native markup may display narrowly recognizable machine tokens, structured JSON objects/arrays, or keyboard notation, never arbitrary prose. Complete URL/path literals are data in any sink (not surrounding prose or a separator). Decorative/machine/JSON child exceptions do not apply to accessible-label/title/placeholder/alt attributes or to neighboring prose. No filename/component-name or suppression allowlist.
Validation plan
- Behavioral fixtures reproduce the four reviewed #2559 shapes (including the
original local
reason, spread/map cost array, props-based accessible name, and hidden JSX middle dot). Run them against the pre-change config first. - Table-driven positives/negatives exercise every sink, local aliases and scope shadowing, valid localization/formatting/data, and exception containment.
- Execute the real gate in a test-owned miniature UI: new file/count fails, localized replacement requires baseline shrink, re-recorded debt passes, and suppression/policy changes cannot bypass enforcement. Retain the existing count-ratchet limitation: same-file/same-rule replacement at equal count is not site-identity enforcement.
- Record only measured new-rule debt on unchanged
ui/src; compare every unrelated violation and suppression allowance to the base byte-for-byte. - Focused lint suites,
npm run lint, test typechecking, and UI build locally; remaining repository checks in CI. Exact-head Codex review, passing applicable CI, and zero unresolved threads are required. Do not merge or deploy.
Implemented policy and analysis limits
avibe/localized-user-text is an error in ui/eslint.config.js and pinned in
lintPolicy.mjs. Applicability is relative to the UI ESLint working directory:
src/**/*.tsx, excluding *.test.tsx, *.spec.tsx, and __tests__ directories.
The rule also treats the explicit children prop as a child sink. It reports
one diagnostic per offending expression/attribute sink or literal JSX text node;
using the same bad binding in both a title and a child yields two diagnostics.
The analysis follows unmodified, identifier-bound const initializers in their
actual lexical scope (including aliases), TS casts/non-null/satisfies wrappers,
conditionals, logical output branches, arrays/spreads, final sequence values,
join separators and receivers, filter receivers, and map/flatMap inline
or const callback return expressions. It ignores conditions and logging inside
callbacks, and stops at nested functions. Cycles terminate. Literal glue is
checked even when inputs are component props with unknown provenance.
This deliberately does not resolve imports, helper return values, arbitrary
object properties/destructuring, mutations, state, callback argument flow, or
cross-component prop flow. Ordinary calls (including t, serverText, Intl
and the existing formatNameList/formatSentences/number helpers) are opaque
output boundaries: their keys and arguments are not assumed to be output copy.
A helper can therefore hide unlocalized text; this is not proof that every UI
string is localized. Whitespace-only JSX formatting nodes and empty string
expressions are ignored; explicit nonempty string expressions/joiners are not.
No punctuation scan runs outside user-facing sinks.
A named Trans import from react-i18next (including an import alias) with an
i18nKey owns its fallback JSX text, including component children. Unverified
same-name components do not. Attributes and composed expression children still
get checked inside a Trans subtree.
Exceptions are content-shaped, not file/component allowlists:
- A direct native
spanwith literal truearia-hidden, no spread attributes, and exactly one of the rule's small icon glyph set may display that glyph. The original hidden middle dot remains an error. Prose and labels remain errors. - Complete whitespace-free HTTP(S)/WS(S) URLs with a hostname and simple explicit absolute/relative/home paths are data, including in titles/placeholders. A lone slash or text around the resource is not exempt. String glue is never exempt.
- Native
code/sampmay display recognizable compound identifiers/flags;code/samp/premay display a complete parsed JSON object/array.kbdmay display narrowly recognized keyboard notation. These do not exempt attributes, descendants, or arbitrary prose, and are not a general programming-language parser. Other existing technical display may conservatively remain baselined; do not translate a protocol command merely to silence it. A future exception needs a bounded content contract plus positive and escape-hatch tests.
Initial measured baseline
Measured against unchanged ui/src at base
055870279641fd86a5f501e6c67310ccde28194a:
| Ledger | Before | After | Delta |
|---|---|---|---|
| New localized-user-text diagnostics | 0 | 322 across 102 files | +322, initial rollout only |
| All unrelated error allowances | 471 | 471 | 0 |
| All inline-suppression allowances | 44 | 44 | 0 |
| Measured TS/TSX domain | 1111 | 1111 | 0 |
Every per-file new-rule count is in ui/eslint-baseline.json; it is the only
ledger, not duplicated here. All unrelated per-file/rule counts, suppressions,
and rationales compare equal to the base. No source or locale files changed.
The initial diagnostics include real sentence/accessible-name composition,
ordinary copy, and conservative technical/glyph display; this is not a claim
that every diagnostic should become translated prose.
The gate still freezes counts, not site identities. Replacing one violation with another of this same rule in this same file at equal count can pass. New pairs, increased counts, newly suppressed messages, and stale allowances cannot. This accepted residual is tested explicitly rather than obscured by a second ledger.
Validation evidence
- Before enabling the rule, all four historical fixture tests failed because the real config returned zero localized-text errors; afterward all four pass.
localizedUserText.test.mjsexecutes the real ESLint config for the historical forms, all sinks, local indirection, valid locale/formatter/data paths and narrow exception containment. Existing convention/policy/baseline tests remain.localizedUserTextGate.test.mjsruns realnpm run lintin test-owned miniature UI trees: new files/counts fail; localized replacements force shrink; re-recorded shrink passes; equal-count replacement retains the documented residual; suppressions, inline overrides and severity demotion cannot bypass the gate.npm run lint,npm run typecheck:tests, andnpm run buildpass locally. Build retains its pre-existing browser-crypto/chunk-size warnings. No Incus update, service change, runtime deployment or manual UI-copy rewrite is needed for this lint-only change.