Skip to content

The three translated READMEs still carry the pre-redesign structure #795

Description

@MongLong0214

Next action: port the English README's information architecture to README.ko.md, README.ja.md and README.zh-CN.md. Nothing blocks it — the English side is settled and merged.

#794 rebuilt README.md against the README redesign SSOT and left the three translations on the structure that preceded it. A reader who follows the language links from the English page lands on a different document, not a translated one.

Measured on the merge commit:

file lines ## headings animated logo hero
README.md 388 13 yes yes
README.ko.md 466 20 no yes
README.ja.md 472 20 no yes
README.zh-CN.md 452 20 no yes

The tests still pass, which is the point worth stating plainly: the suites assert per-file contracts — the install pin, the guard figures, the exposure table, the refs/notes/* distinction, section order — and each translation still satisfies its own. Nothing checks that the four files describe the same product in the same order, so the divergence is invisible to CI.

What the port has to carry

  • The brand block: assets/readme/commitlore-logo.svg at 440px with alt in the file's language, replacing the retired commitlore-mark.svg reference if one is still there.
  • The 13-heading structure and its <!-- README:* --> markers.
  • The facts restored during the English rewrite, since the translations were never missing them and must not lose them in the port: the docs: correct measured retrieval claim #167 exposure table, the refs/notes/* trailers-versus-notes distinction, the host-policy sentence, guard precision 44.8% / recall 22.0%, and the install promise.

Two decisions the port inherits

Both were made on the English file in #794 and should be applied rather than re-litigated per language, or the four files diverge again on meaning instead of structure:

  1. Evidence now precedes limits, reversing The README asks a cold reader for four minutes before it earns one #450. The boundary The README asks a cold reader for four minutes before it earns one #450 wanted a reader to meet first is carried inside the evidence section. test/readme-order.test.ts asserts only that neither section precedes the automation boundary.
  2. Stop re-reviewing the same bad idea. is the hero line again. It had been moved out of the hero deliberately — the comment in test/readme-order.test.ts records why: at 22% guard recall it implies a judgement the product cannot make. The SSOT puts it back. Worth knowing before it is translated three more times.

Worth adding while the files are open

A parity assertion, so the next divergence fails CI instead of waiting for a reader to find it: same heading count, same marker set, same asset references across all four.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions