docs(ui): name the translator helper the code actually declares - #322
Merged
Merged
Conversation
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.
Owner
Author
|
Self-review (committer; What I verified before merging
Scope note: no issue was opened for this; it is a consistency fix on the |
This was referenced Sep 29, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 isT, declared as a hoisted function inui/js/api.js; that same gate names it in its own assertion text (ui/js/api.js 的 T("key") ...), and the contract inui/README.mdnames it too (T("err.network")/T("err.http", {n})). So the code, the gate and the documented contract all agree onT— 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
Tdeclaration, and whose message namesT("err.http", { n })as the fix.trwas 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 throughtr(...)"), so a contributor obeying it literally would call an undefined identifier. Theapi.jssentence is the justification for bypassingERR_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 namesT()(the declaration directly above it) and lists the three keys this file owns, instead oftr().src/i18n_pack.rs— rule ③'s comment saysT("err.http", { n: … })and points at theapi.jsdeclaration, instead oftr().ui/index.html—api.jscache-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通过tr(inui/js/andsrc/was these two comments.Checklist
docs/)docs(ui): ...)