From 76ac59238b9633df9b7a1e10518bcde16ffe0702 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Salavisa?= Date: Mon, 3 Aug 2026 21:44:11 +0200 Subject: [PATCH] docs(i18n): record how to trust the removed-literal check (#2226) Co-authored-by: Kandev Agent --- docs/i18n.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/i18n.md b/docs/i18n.md index 06f7cca2e0..02ee2aedc8 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -672,6 +672,44 @@ hoisted to a constant, or the real thing. It narrows the diff for a human; it does not decide. `--base ` overrides the `origin/main` fork point, and `--all` widens past prose to identifier-shaped strings. +Some benign findings recur and are worth recognising rather than investigating: +an array of fragments collapsed into one comma-separated value is accepted +because every fragment survives verbatim inside the join — the safe property is +that the collapse is **concatenative**, not that it is an array, and a collapse +that also *rewords* is reported, correctly. The shape to be wary of is not +"array collapsed to string", it is "collapse that also edits". + +### Prove it can fail, before you believe it passed + +**A pass from this check is worth exactly what its ability to fail is worth.** +After a clean run, reword one string your diff removed, confirm the check +reports it, and restore. This is not diligence; it is the only way to tell a +check that read your diff and found nothing from one that could not have failed. +Both print the same tick. + +That distinction is not hypothetical. Every defect found in this tool during +review had the same signature — *it returned a pass it had not earned* — and not +one was visible to its own unit tests, because those assume a well-formed +catalog and a committed tree. A message that was nothing but a placeholder +compiled to a match-anything pattern and accepted every string in the +repository. The "after" side read `HEAD` while the file list came from the +working tree, so uncommitted edits were invisible and it printed a tick *with +the correct file count*. Each was found by someone running it for real and +declining to believe the result. + +**The probe must be a rewrite, and it must change the opening words.** Two +probes proved nothing before this was written down, and neither was the +author's fault: + +- an **append** is absorbed by rule 3 by design (`message.includes(norm)`), so + `"Try asking"` → `"Try asking now"` always passes; +- a rewrite that **keeps the opening words** is absorbed by rule 2, because the + literal prefix is what the pattern anchors on — a probe on a + `"Delete {{name}}"`-shaped message that still begins `Delete ` tests nothing. + +A good probe changes the whole sentence: `"What do you want to change?"` → +`"What would you like to configure?"` is reported. + **Its coverage is partial, and a clean run is evidence rather than proof.** Rule 2 is only as tight as the literal text around a message's placeholders, so a message with too little of it earns no pattern at all — it needs two words of @@ -698,6 +736,17 @@ string like `"3 of 9"` is reported and classified by hand — the right directio for an advisory check, since a false positive costs someone ten seconds and a false negative is the failure the check exists to prevent. +**The general rule is: verify against the authority, not against a copy.** The +route table is the authority for what renders — a `page.tsx` that renders a +component is not evidence that page is the live surface, and reading one led to +a changelog surface being treated as live when `SETTINGS_ROUTES` never mounted +it. `origin/main` is the authority for what ships — a fetched or pasted copy of +a script is not the script, and testing one produced a defect report against +code already fixed on the branch. The subtlest instance was an agent quoting a +colleague's description of a file while its own measurement of that file sat +unread in its terminal. All three look like diligence: something was read, +something was run. None was the thing that decides. + The underlying defect is the duplication itself. Unreferenced pages that re-render live copy will drift again, and the next migration inherits the same trap — which is why deleting a dead twin is a correctness change, not tidiness.