docs: move translated READMEs under docs/readme (#2165)

Move all 18 translated READMEs into docs/readme/ and keep the English entry at the repository root. Update navigation, guide/image paths, website discovery and documentation checks together.

Preserve the contributor's work and current main content. Cover every translated command and HTML destination, and repair the verified Persian heading fragments.

Validation: 203 focused tests on the synchronized head, plus 119 tests and documentation checks on the integration with main fc0dbe7f9; 1,501 local references and 399 authored fragments verified. The complete CI workflow passes. The upstream x64 dylib fixture correction is included; an unchanged-checkout rerun cleared the earlier deadline timing assertion.

Closes #2141

Co-authored-by: Aimal Khan <94559553+aimalexe@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Aimal Khan
2026-10-13 22:25:32 +08:00
committed by GitHub
co-authored by Kaoru0822 factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent 865c35e25a
commit cbe769b504
29 changed files with 1108 additions and 956 deletions
+1
View File
@@ -363,6 +363,7 @@ export const SCOPES = {
"website/**",
"scripts/*website*.py",
"README*.md",
"docs/readme/README*.md",
".github/workflows/website-check.yml",
".github/workflows/website-pages.yml",
],
+58 -11
View File
@@ -1,13 +1,41 @@
import { readFile, readdir, stat } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
const readmeLinkTargets = (content, language = "en") =>
[...content.matchAll(/\]\(([^)\s]+)\)/gu)]
.map((match) => match[1] ?? "")
const repoRelative = (root, from, target) => {
const index = target.search(/[#?]/u);
const pathPart = index === -1 ? target : target.slice(0, index);
const suffix = index === -1 ? "" : target.slice(index);
if (pathPart.length === 0 || /^[a-z][a-z0-9+.-]*:/iu.test(pathPart))
return target;
const absolute = resolve(root, dirname(from), pathPart);
const withinRepo = relative(root, absolute);
if (
withinRepo === ".." ||
withinRepo.startsWith(`..${sep}`) ||
isAbsolute(withinRepo)
)
return target;
return `${withinRepo.split(sep).join("/")}${suffix}`;
};
const isLanguageNavigation = (target) => {
const path = target.split(/[#?]/u)[0];
return (
path === "README.md" ||
/^docs\/readme\/README_[A-Za-z0-9-]+\.md$/u.test(path)
);
};
const readmeDestinations = (content) => [
...content.matchAll(/\]\(([^)\s]+)\)/gu),
...content.matchAll(/\b(?:src|href)="([^"]+)"/gu),
];
const readmeLinkTargets = (root, from, content, language = "en") =>
readmeDestinations(content)
.map((match) => repoRelative(root, from, match[1] ?? ""))
.filter(
(target) =>
!target.startsWith("#") &&
!/^README(?:_[A-Za-z0-9-]+)?\.md$/u.test(target),
(target) => !target.startsWith("#") && !isLanguageNavigation(target),
)
.map((target) => {
if (language === "en" || !URL.canParse(target)) return target;
@@ -70,9 +98,19 @@ export const documentationFactIssues = async (root, catalog) => {
const issues = await skillReferenceIssues(
join(root, "skills/reverse-engineer-anything"),
);
const readmePaths = (await readdir(root))
.filter((path) => /^README(?:_[A-Za-z0-9-]+)?\.md$/u.test(path))
.sort();
const translatedFolder = join(root, "docs/readme");
let translatedNames = [];
try {
translatedNames = await readdir(translatedFolder);
} catch (cause) {
if (cause?.code !== "ENOENT") throw cause;
}
const readmePaths = [
"README.md",
...translatedNames
.filter((name) => /^README_[A-Za-z0-9-]+\.md$/u.test(name))
.map((name) => `docs/readme/${name}`),
].sort();
const readmes = new Map();
for (const path of readmePaths) {
const content = await readFile(join(root, path), "utf8");
@@ -94,7 +132,11 @@ export const documentationFactIssues = async (root, catalog) => {
);
}
}
const canonicalLinks = readmeLinkTargets(readmes.get("README.md") ?? "");
const canonicalLinks = readmeLinkTargets(
root,
"README.md",
readmes.get("README.md") ?? "",
);
const languageInventory = JSON.parse(
await readFile(join(root, "website/locales/languages.json"), "utf8"),
);
@@ -104,7 +146,12 @@ export const documentationFactIssues = async (root, catalog) => {
for (const path of readmePaths.filter((path) => path !== "README.md"))
if (
JSON.stringify(
readmeLinkTargets(readmes.get(path) ?? "", readmeLanguages.get(path)),
readmeLinkTargets(
root,
path,
readmes.get(path) ?? "",
readmeLanguages.get(path),
),
) !== JSON.stringify(canonicalLinks)
)
issues.push(`${path}: documentation links differ from README.md`);
+3 -1
View File
@@ -261,7 +261,9 @@ class WebsiteTranslationChecks(unittest.TestCase):
inventory = [item for item in languages(ROOT) if item["code"] in {"en", "zh-CN", "ar"}]
(root / "website/locales/languages.json").write_text(json.dumps(inventory))
for item in inventory:
(root / item["readme"]).write_text("# REA\n")
destination = root / item["readme"]
destination.parent.mkdir(parents=True, exist_ok=True)
destination.write_text("# REA\n")
WEBSITE.sync_pages(root)
extract_catalogs(root)
yield root
+18 -3
View File
@@ -25,11 +25,27 @@ LITERALS = {"REA", "Reverse Engineer Anything", "REA · Reverse Engineer Anythin
FALLBACK_NOTICE = "Translation is being updated. Read this page in English for now."
def readme_edition_paths(root):
"""Return repo-relative README editions: root English plus docs/readme translations."""
editions = set()
if (root / "README.md").is_file():
editions.add("README.md")
folder = root / "docs" / "readme"
if folder.is_dir():
editions.update(
f"docs/readme/{path.name}"
for path in folder.glob("README_*.md")
if path.is_file()
)
return editions
def languages(root):
"""Load the website language inventory and check it against README editions."""
path = root / "website/locales/languages.json"
editions = readme_edition_paths(root)
if not path.exists():
if any(root.glob("README_*.md")):
if any(edition != "README.md" for edition in editions):
raise ValueError("Missing languages.json for the translated README editions")
return [{"code": "en", "name": "English", "readme": "README.md", "dir": "ltr"}]
data = json.loads(path.read_text(encoding="utf-8"))
@@ -49,8 +65,7 @@ def languages(root):
raise ValueError(f"Duplicate README edition: {item['readme']}")
codes.add(item["code"])
filenames.add(item["readme"])
readmes = {path.name for path in root.glob("README*.md")}
if readmes and ({item["readme"] for item in data} != readmes):
if editions and ({item["readme"] for item in data} != editions):
raise ValueError("Website languages must match the README language editions")
return data