Skip to content

docs(ui): name the translator helper the code actually declares - #322

Merged
argszero merged 1 commit into
mainfrom
docs/name-the-translator-helper-that-exists
Sep 28, 2026
Merged

argszero merged 1 commit into
mainfrom
docs/name-the-translator-helper-that-exists

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Two carriers in this repository told the next reader to call tr(...). No function of that name exists anywhere in the repository. The helper is T, declared as a hoisted function in ui/js/api.js; that same gate names it in its own assertion text (ui/js/api.js 的 T("key") ...), and the contract in ui/README.md names it too (T("err.network") / T("err.http", {n})). So the code, the gate and the documented contract all agree on T — only these two comments disagreed.

Provenance is drift, not a trade-off. Both were introduced by 6f8b599 (#183, C2029) — the very commit that wrote the T declaration, and whose message names T("err.http", { n }) as the fix. tr was therefore never a real symbol here: it is a drafting leftover that landed in the prose and survived because comments are stripped before every gate reads the corpus.

The instance that matters is in src/i18n_pack.rs: that sentence is normative ("the fallback must go through tr(...)"), so a contributor obeying it literally would call an undefined identifier. The api.js sentence is the justification for bypassing ERR_MAP; it now points at the declaration instead of restating a name that can drift again.

No new gate, deliberately (see the commit body): a lexer-level rule of the form "every funclet named in a comment must exist in the code" cannot be written without an exemption list, and this repository's convention for prose claims is to fix the data. The measurements are recorded in the commit message.

Related Issue

None. Reported as a docs/consistency fix; no issue was opened for it.

Changes

  • ui/js/api.js — the fallback comment names T() (the declaration directly above it) and lists the three keys this file owns, instead of tr().

  • src/i18n_pack.rs — rule ③'s comment says T("err.http", { n: … }) and points at the api.js declaration, instead of tr().

  • ui/index.html — api.js cache-bust token bumped (20260914-13 -> 20260929-1) because the file's bytes changed.

  • 功能/修复说明 (comment-only: two wrong helper names corrected to the one the code declares)

  • 涉及配置/数据结构的改动已同步示例文件 (not applicable — no config/data change)

Tests

  • cargo test 全部通过 — 421 passed; 0 failed (unchanged count: comment-only change)
  • cargo fmt --check 通过
  • 新增/更新了单元测试(如适用)— not applicable; the change is prose only and cannot alter behavior. Evidence is the A/B by inspection recorded in the commit body: before the change the only tr( in ui/js/ and src/ was these two comments.

Checklist

  • 分支命名符合约定(docs/)
  • Commit message 使用 Conventional Commits 格式(docs(ui): ...)
  • 单一职责,改动最小化(3 files, +5/−3; two comments plus the token bump they require)

Two carriers told the next reader to call `tr(...)`. No function of that
name exists anywhere in the repository: the helper is `T`, declared as a
hoisted function in `ui/js/api.js`, named by that same gate's own
assertion text (`ui/js/api.js 的 T("key") ...`), and named by the
contract in `ui/README.md`. The code, the gate and the documented
contract therefore all agree on `T`; only these two comments disagreed.

Provenance is drift, not a trade-off: both were introduced by 6f8b599
(#183, C2029) - the very commit that wrote the `T` declaration and whose
message names `T("err.http", { n })` as the fix. So `tr` was never a real
symbol here; it is a drafting leftover that landed in the prose and lived
on because every comment is stripped before the gates read the corpus.

The instance that matters is in `src/i18n_pack.rs`: that sentence is
normative ("the fallback must go through `tr(...)`"), so a contributor
obeying it would call an undefined identifier. The api.js sentence is the
justification for bypassing `ERR_MAP`, and it now points at the
declaration instead of restating a name that can drift again.

No new gate. A lexer-level rule ("every funclet named in a comment must
exist in the code") is not implementable without an exemption list:
measured over `src/**/*.rs`, `ui/**/*.js`, `ui/index.html`, `*.md` and
CSS, 28 backticked identifiers cited in comments exist nowhere in code
and every one is legitimate (commit SHAs such as `ce6d0db`, simulated
probe leg names such as `m_drop`, clippy lint names such as
`type_complexity`, prose labels such as `composite`, and one
self-declared historical `seed()`), and the near-miss is invisible to a
membership test anyway because `tr` collides with the HTML `<tr>` tag and
a local `const tr` in `app.js`. This repository's convention for prose
claims is to fix the data rather than gate it.

Verification:
- A/B by inspection of the two carriers: the only `tr(` in `ui/js/` and
  `src/` was these two comments; removed.
- `cargo test` 421 passed, 0 failed (unchanged count: comment-only).
- `cargo fmt --check` clean; `cargo clippy --all-targets -- -D warnings`
  clean (rustc 1.86 / CI toolchain).
- `ui/index.html` cache-bust for `api.js` bumped per convention
  (`20260914-13` -> `20260929-1`), since the file's bytes changed.
@argszero

Copy link
Copy Markdown
Owner Author

Self-review (committer; allow_self_merge is on for this repo, and GitHub does not let an author approve their own PR, so this is a plain comment):

What I verified before merging

  1. The name that does not exist — grep -rnE '(^|[^A-Za-z0-9_])tr\(' ui/js src matched exactly two lines on the base commit, both comments; zero matches after the change. No function tr, no window.tr, no tr: export anywhere in ui/ or src/.
  2. The direction is forced, not chosen — three carriers state the helper's name: the declaration in ui/js/api.js, this gate's own assertion text (ui/js/api.js 的 T("key") ...), and the contract in ui/README.md (T("err.network") / T("err.http", {n})). All three say T. Renaming the function to tr is refuted by the repository's own rule: the shared scanner scan_t_literals recognises only the T("literal") call shape, and ui/js/api.js says so in prose 30 lines above the change.
  3. Provenance — git log -S'tr(' -- ui/js/api.js and -S'必须走 tr(' -- src/i18n_pack.rsboth return a single commit, 6f8b599 (#183, C2029) — the same commit that added theTdeclaration and whose message namesT("err.http", { n })`. The wrong name was never a symbol.
  4. Why no gate — measured: 28 backticked identifiers cited in comments across src/**/*.rs, ui/**/*.js, ui/index.html, *.md and CSS exist nowhere in the code, and every one is legitimate (commit SHAs, simulated probe-leg names, clippy lint names, prose labels, one self-declared historical seed()). A membership test also cannot see this particular near-miss, because tr collides with the HTML <tr> tag and with a local const tr in app.js. Fixing the data is this repository's convention for prose claims.
  5. Gates — cargo test 421 passed / 0 failed (unchanged count: prose-only), cargo fmt --check clean, cargo clippy --all-targets -- -D warnings clean, on the tree this PR would land on. CI: test / fmt / clippy pass, msrv pass.
  6. Cache-bust — api.js bytes changed, so its ?v= token is bumped in ui/index.html per convention.

Scope note: no issue was opened for this; it is a consistency fix on the doc-comment-claims axis, where this repository's standing verdict is to correct the prose and not to add an assertion.

@argszero
argszero merged commit 8d9f97e into main Sep 28, 2026
2 checks passed
@argszero
argszero deleted the docs/name-the-translator-helper-that-exists branch September 28, 2026 22:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant