feat(website): add language infrastructure for translated pages
Prepare translated versions of the home, Get started, Guides and FAQ pages in zh-Hans, zh-Hant, ja, ko, de and fr. English stays at the root and each language lives under its own directory. No translated page exists yet, so English pages only gain an og:locale tag. - LANGUAGES in website.py owns each language's directory, lang/hreflang tag, menu name and og:locale; locales/<language>.json holds the shared UI text (non-English locales start as English placeholders). - sync renders the header, footer and sharing regions in the page's language: localized navigation with an EN badge on English-only targets, a native-details language menu (same page, else the language's reviewed home, else omitted), hreflang alternates with x-default, og:locale alternates and the brand link to the language's home. - Translations record source-sha256 and status (draft or reviewed). Drafts are noindex and stay out of the sitemap, menus, hreflang and navigation. - sync copies every Copy-targeted code block from English by ID, and fills the website:translation-notice region when the English text has changed. The hash leaves out shared regions and those code blocks. - The verifier checks records, copied code, ID/Copy/data-msg parity while fresh, whitespace between CJK characters in ja/zh, and the page's lang. An out-of-date translation, inline-code differences, links to English pages with a reviewed translation and English placeholder UI strings are warnings, shown as GitHub annotations and in the job summary. - New commands: `translate <language> <route>` creates a draft and `translations` reports status, freshness and OS names to confirm. - styles.css adds per-language CJK font stacks, CJK heading, emphasis and line-breaking rules, German hyphenation, and the menu, badge and notice. - The publisher runs sync after the checks so notices are current. - website/translation.md documents the workflow, rules, register, glossary (with Korean), OS names to confirm and the review checklist. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
80f6365523
commit
ce58aebc0e
@@ -65,6 +65,9 @@ jobs:
|
||||
node-version-file: .nvmrc
|
||||
- name: Check shared HTML, links, assets and contributor workflows
|
||||
run: python3 scripts/website.py check
|
||||
# An out-of-date translation only warns in checks; publish it with its notice.
|
||||
- name: Refresh translation notices
|
||||
run: python3 scripts/website.py sync
|
||||
- name: Record the published commit
|
||||
run: |
|
||||
python3 - <<'PY'
|
||||
|
||||
+191
-2
@@ -3,6 +3,7 @@
|
||||
import contextlib
|
||||
import importlib.util
|
||||
import io
|
||||
import re
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
import tempfile
|
||||
@@ -137,7 +138,7 @@ class WebsiteMaintenanceChecks(unittest.TestCase):
|
||||
def test_shared_edits_preserve_body_and_catch_drift_before_rewriting(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
for name in ("public", "templates"):
|
||||
for name in ("public", "templates", "locales"):
|
||||
shutil.copytree(ROOT / "website" / name, root / "website" / name)
|
||||
page = root / "website/public/blog/touhou-reconstruction/index.html"
|
||||
original = page.read_text()
|
||||
@@ -159,7 +160,7 @@ class WebsiteMaintenanceChecks(unittest.TestCase):
|
||||
def test_new_page_escapes_metadata_stays_a_draft_and_joins_sitemap_when_ready(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
for name in ("public", "templates"):
|
||||
for name in ("public", "templates", "locales"):
|
||||
shutil.copytree(ROOT / "website" / name, root / "website" / name)
|
||||
site = root / "website/public"
|
||||
page = WEBSITE.new_page(root, "blog/new-example", 'A <test> & "result"', 'Check "quotes" & <markup>.')
|
||||
@@ -242,5 +243,193 @@ class WebsiteMaintenanceChecks(unittest.TestCase):
|
||||
worker.join()
|
||||
|
||||
|
||||
|
||||
def site_copy(directory):
|
||||
"""Copy the authored website inputs into a temporary repository root."""
|
||||
root = Path(directory)
|
||||
for name in ("public", "templates", "locales"):
|
||||
shutil.copytree(ROOT / "website" / name, root / "website" / name)
|
||||
return root
|
||||
|
||||
|
||||
def quietly(function, *arguments):
|
||||
"""Run a command helper without its progress output."""
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
return function(*arguments)
|
||||
|
||||
|
||||
def mark_reviewed(path):
|
||||
"""Apply the reviewer's change: reviewed status and date, without noindex.
|
||||
|
||||
A reviewed translation has its own search title, so give the test page one.
|
||||
"""
|
||||
source = re.sub(r"<title>(.*?)</title>", r"<title>\1 (zh-Hant)</title>", path.read_text(), count=1)
|
||||
source = source.replace('status="draft"', 'status="reviewed" reviewed="2026-10-11"', 1)
|
||||
path.write_text(source.replace(' <meta name="robots" content="noindex" />\n', "", 1))
|
||||
|
||||
|
||||
def translation_errors(root):
|
||||
"""Return the verifier's translation errors and warnings for a site copy."""
|
||||
return VERIFY.check_translations(root, VERIFY.parse_pages(root / "website/public"))
|
||||
|
||||
|
||||
class WebsiteTranslationChecks(unittest.TestCase):
|
||||
"""Create translations through the contributor command and check what readers get."""
|
||||
|
||||
def test_translate_creates_an_unlinked_noindex_draft(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = site_copy(directory)
|
||||
site = root / "website/public"
|
||||
english = (site / "get-started/index.html").read_text()
|
||||
page = quietly(WEBSITE.new_translation, root, "zh-hant", "get-started")
|
||||
source = page.read_text()
|
||||
self.assertEqual(page, site / "zh-hant/get-started/index.html")
|
||||
self.assertIn('<html lang="zh-Hant">', source)
|
||||
self.assertIn('<meta name="robots" content="noindex" />', source)
|
||||
self.assertEqual(
|
||||
WEBSITE.translation_record(source),
|
||||
{"source-sha256": WEBSITE.source_digest(english), "status": "draft"},
|
||||
)
|
||||
self.assertIn('href="../../assets/styles.css"', source)
|
||||
self.assertIn('<a href="../../faq/">', source)
|
||||
self.assertIn('href="../../guides/javascript/"', source)
|
||||
self.assertIn('<a class="brand" href="../../"', source)
|
||||
self.assertIn(
|
||||
'<a href="../../zh-hant/get-started/" class="nav-start" aria-current="page">Get started</a>', source
|
||||
)
|
||||
self.assertIn(
|
||||
'<a href="../../showcase/" hreflang="en">Showcases<span class="nav-badge" lang="en">EN</span></a>',
|
||||
source,
|
||||
)
|
||||
self.assertIn('<li><a href="../../get-started/" hreflang="en" lang="en">English</a></li>', source)
|
||||
self.assertIn('<meta property="og:locale" content="zh_TW" />', source)
|
||||
self.assertNotIn('rel="alternate"', source)
|
||||
self.assertIn(WEBSITE.NOTICE_START + WEBSITE.NOTICE_END, source)
|
||||
self.assertEqual(english, (site / "get-started/index.html").read_text())
|
||||
errors, warnings = translation_errors(root)
|
||||
self.assertEqual(errors, [])
|
||||
self.assertEqual([file for file, _ in warnings], ["website/locales/zh-hant.json"])
|
||||
self.assertEqual(VERIFY.check_site(site)[3], [])
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
PREPARE.prepare_sitemap(site)
|
||||
self.assertNotIn("zh-hant", (site / "sitemap.xml").read_text())
|
||||
for language, route, message in (
|
||||
("zh-hant", "get-started", "already exists"),
|
||||
("en", "faq", "Choose one of"),
|
||||
("ja", "missing", "No English page"),
|
||||
("ja", "zh-hant/get-started", "without a language directory"),
|
||||
("ja", "../outside", "directory route"),
|
||||
):
|
||||
with self.subTest(language=language, route=route):
|
||||
with self.assertRaisesRegex(ValueError, message):
|
||||
quietly(WEBSITE.new_translation, root, language, route)
|
||||
|
||||
def test_reviewed_translations_join_menus_hreflang_and_the_sitemap(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = site_copy(directory)
|
||||
site = root / "website/public"
|
||||
mark_reviewed(quietly(WEBSITE.new_translation, root, "zh-hant", "get-started"))
|
||||
quietly(WEBSITE.sync_pages, root)
|
||||
english = (site / "get-started/index.html").read_text()
|
||||
for tag, url in (
|
||||
("en", "https://rea.tools/get-started/"),
|
||||
("zh-Hant", "https://rea.tools/zh-hant/get-started/"),
|
||||
("x-default", "https://rea.tools/get-started/"),
|
||||
):
|
||||
self.assertIn(f'<link rel="alternate" hreflang="{tag}" href="{url}" />', english)
|
||||
self.assertIn('<meta property="og:locale:alternate" content="zh_TW" />', english)
|
||||
self.assertIn(
|
||||
'<li><a href="../zh-hant/get-started/" hreflang="zh-Hant" lang="zh-Hant">繁體中文</a></li>', english
|
||||
)
|
||||
self.assertNotIn("language-menu", (site / "faq/index.html").read_text())
|
||||
translated = (site / "zh-hant/get-started/index.html").read_text()
|
||||
self.assertIn('<meta property="og:locale:alternate" content="en_US" />', translated)
|
||||
|
||||
# A reviewed home page becomes the menu's fallback for untranslated pages.
|
||||
mark_reviewed(quietly(WEBSITE.new_translation, root, "zh-hant", "/"))
|
||||
quietly(WEBSITE.sync_pages, root)
|
||||
self.assertIn(
|
||||
'<li><a href="../zh-hant/" hreflang="zh-Hant" lang="zh-Hant">繁體中文</a></li>',
|
||||
(site / "faq/index.html").read_text(),
|
||||
)
|
||||
translated = (site / "zh-hant/get-started/index.html").read_text()
|
||||
self.assertIn('<a class="brand" href="../../zh-hant/"', translated)
|
||||
home = (site / "zh-hant/index.html").read_text()
|
||||
self.assertIn('href="get-started/"', home)
|
||||
self.assertIn('href="../showcase/"', home)
|
||||
self.assertIn('href="../assets/styles.css"', home)
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
PREPARE.prepare_sitemap(site)
|
||||
sitemap = (site / "sitemap.xml").read_text()
|
||||
self.assertIn("https://rea.tools/zh-hant/get-started/", sitemap)
|
||||
self.assertIn("https://rea.tools/zh-hant/", sitemap)
|
||||
self.assertEqual(VERIFY.check_site(site)[3], [])
|
||||
self.assertEqual(translation_errors(root)[0], [])
|
||||
|
||||
def test_english_commands_sync_and_text_changes_show_a_notice(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = site_copy(directory)
|
||||
site = root / "website/public"
|
||||
english_path = site / "get-started/index.html"
|
||||
page = quietly(WEBSITE.new_translation, root, "zh-hant", "get-started")
|
||||
english = english_path.read_text()
|
||||
|
||||
command = "npm install --global rea-agents</code>"
|
||||
english_path.write_text(english.replace(command, "npm install --global rea-agents@latest</code>", 1))
|
||||
with self.assertRaisesRegex(ValueError, "Shared HTML is stale: zh-hant/get-started/index.html"):
|
||||
quietly(WEBSITE.sync_pages, root, True)
|
||||
quietly(WEBSITE.sync_pages, root)
|
||||
self.assertIn("rea-agents@latest</code>", page.read_text())
|
||||
self.assertNotIn("translation-notice\"", page.read_text())
|
||||
self.assertEqual(translation_errors(root)[0], [])
|
||||
|
||||
text = "<p>Restart your client when setup finishes.</p>"
|
||||
changed = english_path.read_text().replace(text, "<p>Restart your client after setup.</p>", 1)
|
||||
english_path.write_text(changed)
|
||||
self.assertEqual(quietly(WEBSITE.sync_pages, root, True), [page])
|
||||
errors, warnings = translation_errors(root)
|
||||
self.assertEqual(errors, [])
|
||||
self.assertTrue(any("has changed since this translation" in message for _, message in warnings))
|
||||
quietly(WEBSITE.sync_pages, root)
|
||||
self.assertIn(
|
||||
'<p class="translation-notice" role="note">The English page has changed since this translation. '
|
||||
'<a href="../../get-started/" hreflang="en">Read the English version.</a></p>',
|
||||
page.read_text(),
|
||||
)
|
||||
report = quietly(WEBSITE.translation_report, root)
|
||||
self.assertIn(f' after updating the translation, record source-sha256="{WEBSITE.source_digest(changed)}"', report)
|
||||
|
||||
english_path.write_text(changed.replace("<p>Restart your client after setup.</p>", text, 1))
|
||||
quietly(WEBSITE.sync_pages, root)
|
||||
self.assertNotIn('class="translation-notice"', page.read_text())
|
||||
|
||||
page.write_text(page.read_text().replace("rea-agents@latest</code>", "rea-agents@1</code>", 1))
|
||||
self.assertTrue(any("install-cli must match" in error for error in translation_errors(root)[0]))
|
||||
|
||||
def test_translations_keep_structure_and_cjk_spacing(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = site_copy(directory)
|
||||
page = quietly(WEBSITE.new_translation, root, "zh-hant", "get-started")
|
||||
original = page.read_text()
|
||||
cases = (
|
||||
("<p>Restart your client when setup finishes.</p>", "<p>完成後\n 重新啟動。</p>", "renders as a gap"),
|
||||
('id="install-node"', 'id="node"', "element IDs differ"),
|
||||
('data-copy="install-cli"', 'data-copy="node-check"', "copy buttons differ"),
|
||||
(' <meta name="robots" content="noindex" />\n', "", "draft translation needs"),
|
||||
('status="draft"', 'status="final"', "status must be draft or reviewed"),
|
||||
)
|
||||
for old, new, message in cases:
|
||||
with self.subTest(message=message):
|
||||
self.assertIn(old, original)
|
||||
page.write_text(original.replace(old, new, 1))
|
||||
self.assertTrue(any(message in error for error in translation_errors(root)[0]))
|
||||
page.write_text(original.replace("<p>Restart your client when setup finishes.</p>", "<p>重新啟動 REA 用戶端。</p>", 1))
|
||||
self.assertEqual(translation_errors(root)[0], [])
|
||||
page.write_text(original.replace("<code>node -v</code>", "<code>node -V</code>", 1))
|
||||
errors, warnings = translation_errors(root)
|
||||
self.assertEqual(errors, [])
|
||||
self.assertTrue(any("inline code differs" in message for _, message in warnings))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
+221
-8
@@ -1,6 +1,8 @@
|
||||
"""Check website references, search metadata and the sole production publisher."""
|
||||
|
||||
from collections import Counter
|
||||
from html.parser import HTMLParser
|
||||
import os
|
||||
from pathlib import Path
|
||||
import re
|
||||
import struct
|
||||
@@ -10,7 +12,21 @@ from urllib.parse import unquote, urlsplit
|
||||
import xml.etree.ElementTree as ET
|
||||
from zipfile import BadZipFile, ZipFile
|
||||
|
||||
from website import NOTES_FIXTURES, SITE_ORIGIN, authored_markdown, page_url, sync_pages
|
||||
from website import (
|
||||
LANGUAGES,
|
||||
NOTES_FIXTURES,
|
||||
SITE_ORIGIN,
|
||||
SiteState,
|
||||
authored_markdown,
|
||||
code_block,
|
||||
copy_targets,
|
||||
page_language,
|
||||
page_url,
|
||||
source_digest,
|
||||
sync_pages,
|
||||
synced_code_ids,
|
||||
translation_record,
|
||||
)
|
||||
|
||||
LEGACY_ORIGIN = "morluto.github.io"
|
||||
SITE_TEXT_URL = re.compile(
|
||||
@@ -167,8 +183,9 @@ def check_search_metadata(site, pages):
|
||||
title = page.titles[0].strip() if len(page.titles) == 1 else ""
|
||||
if not title:
|
||||
errors.append(f"{label}: needs exactly one nonempty head title")
|
||||
if page.lang != "en" or page.h1_count != 1:
|
||||
errors.append(f"{label}: needs lang=en and exactly one h1")
|
||||
tag = LANGUAGES[page_language(site, path)[0]].tag
|
||||
if page.lang != tag or page.h1_count != 1:
|
||||
errors.append(f"{label}: needs lang={tag} and exactly one h1")
|
||||
if label in NOTES_FIXTURES and not page.noindex():
|
||||
errors.append(
|
||||
f"{label}: example application must have a head noindex directive"
|
||||
@@ -280,15 +297,21 @@ def check_search_metadata(site, pages):
|
||||
return len(indexable), errors
|
||||
|
||||
|
||||
def check_site(site):
|
||||
"""Check assets, HTML fragment destinations and SVG syntax."""
|
||||
def parse_pages(site):
|
||||
"""Parse every HTML page once for reference, metadata and translation checks."""
|
||||
pages = {}
|
||||
errors = []
|
||||
references = 0
|
||||
for path in sorted(site.rglob("*.html")):
|
||||
parser = HtmlReferences()
|
||||
parser.feed(path.read_text(encoding="utf-8"))
|
||||
pages[path] = parser
|
||||
return pages
|
||||
|
||||
|
||||
def check_site(site):
|
||||
"""Check assets, HTML fragment destinations and SVG syntax."""
|
||||
pages = parse_pages(site)
|
||||
errors = []
|
||||
references = 0
|
||||
if site / "index.html" not in pages:
|
||||
errors.append("website/public/index.html is missing")
|
||||
|
||||
@@ -346,6 +369,190 @@ def check_site(site):
|
||||
return len(pages), references, indexable, errors
|
||||
|
||||
|
||||
# Han, kana and CJK punctuation; a space between two of them renders as a gap.
|
||||
CJK_GAP = re.compile(
|
||||
r"([、-〿-ヿ㐀-䶿一-鿿豈-!-])"
|
||||
r"\s+([、-〿-ヿ㐀-䶿一-鿿豈-!-])"
|
||||
)
|
||||
CODE_TAGS = {"code", "kbd", "pre", "script", "style"}
|
||||
|
||||
|
||||
class TranslationText(HTMLParser):
|
||||
"""Collect prose, inline code and message attributes for comparing translations."""
|
||||
|
||||
def __init__(self, synced):
|
||||
super().__init__()
|
||||
self.synced = set(synced)
|
||||
self.stack = []
|
||||
self.prose = []
|
||||
self.inline_code = Counter()
|
||||
self.messages = Counter()
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
attributes = dict(attrs)
|
||||
self.messages.update(name for name in attributes if name.startswith("data-msg-"))
|
||||
if tag in CODE_TAGS:
|
||||
self.stack.append([tag, attributes.get("id"), ""])
|
||||
|
||||
def handle_startendtag(self, tag, attrs):
|
||||
attributes = dict(attrs)
|
||||
self.messages.update(name for name in attributes if name.startswith("data-msg-"))
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if self.stack and self.stack[-1][0] == tag:
|
||||
name, identifier, text = self.stack.pop()
|
||||
if name in ("code", "kbd") and identifier not in self.synced:
|
||||
self.inline_code[" ".join(text.split())] += 1
|
||||
if self.stack:
|
||||
self.stack[-1][2] += text
|
||||
|
||||
def handle_data(self, data):
|
||||
if self.stack:
|
||||
self.stack[-1][2] += data
|
||||
else:
|
||||
self.prose.append(data)
|
||||
|
||||
|
||||
def translation_warning(path, root, message):
|
||||
"""Return a warning tied to a repository file."""
|
||||
return (path.relative_to(root).as_posix(), message)
|
||||
|
||||
|
||||
def check_translations(root, pages):
|
||||
"""Check translation records, copied code, structure parity and CJK spacing.
|
||||
|
||||
A changed English source is a warning: its translation keeps working, shows a
|
||||
notice after sync and is updated later. Errors cover what sync or the
|
||||
translator controls directly.
|
||||
"""
|
||||
site = root / "website/public"
|
||||
errors = []
|
||||
warnings = []
|
||||
try:
|
||||
state = SiteState(root)
|
||||
except ValueError as error:
|
||||
return [str(error)], []
|
||||
for path, page in pages.items():
|
||||
language, english = page_language(site, path)
|
||||
if language == "en":
|
||||
continue
|
||||
label = path.relative_to(site).as_posix()
|
||||
source = path.read_text(encoding="utf-8")
|
||||
record = translation_record(source)
|
||||
english_path = site / english
|
||||
if not english_path.is_file():
|
||||
errors.append(f"{label}: translates {english}, which does not exist")
|
||||
continue
|
||||
english_source = english_path.read_text(encoding="utf-8")
|
||||
if record is None:
|
||||
errors.append(f"{label}: needs one <!-- website:translation source-sha256=... status=... --> record")
|
||||
continue
|
||||
status = record.get("status")
|
||||
if status not in ("draft", "reviewed"):
|
||||
errors.append(f"{label}: translation status must be draft or reviewed")
|
||||
if status == "draft" and not page.noindex():
|
||||
errors.append(f"{label}: a draft translation needs <meta name=\"robots\" content=\"noindex\" />")
|
||||
if status == "reviewed":
|
||||
if page.noindex():
|
||||
errors.append(f"{label}: remove noindex from a reviewed translation")
|
||||
if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", record.get("reviewed", "")):
|
||||
errors.append(f"{label}: a reviewed translation needs reviewed=\"YYYY-MM-DD\"")
|
||||
fresh = record.get("source-sha256") == source_digest(english_source)
|
||||
if not fresh:
|
||||
warnings.append(translation_warning(
|
||||
path, root,
|
||||
f"The English page {english} has changed since this translation. Update the translation, "
|
||||
"then set source-sha256 to the new value from python3 scripts/website.py translations.",
|
||||
))
|
||||
|
||||
synced = synced_code_ids(english_source)
|
||||
for identifier in synced:
|
||||
expected = code_block(identifier).search(english_source).group(2)
|
||||
found = code_block(identifier).findall(source)
|
||||
if len(found) != 1 or found[0][1] != expected:
|
||||
errors.append(f"{label}: code block {identifier} must match the English page; run sync")
|
||||
|
||||
english_page = pages[english_path]
|
||||
differences = []
|
||||
if page.ids != english_page.ids:
|
||||
differences.append(
|
||||
f"element IDs differ (missing {sorted(english_page.ids - page.ids)}, extra {sorted(page.ids - english_page.ids)})"
|
||||
)
|
||||
if copy_targets(source) != copy_targets(english_source):
|
||||
differences.append("copy buttons differ from the English page")
|
||||
translated = TranslationText(synced)
|
||||
translated.feed(source)
|
||||
original = TranslationText(synced)
|
||||
original.feed(english_source)
|
||||
if translated.messages != original.messages:
|
||||
differences.append("data-msg-* message attributes differ from the English page")
|
||||
for difference in differences:
|
||||
if fresh:
|
||||
errors.append(f"{label}: {difference}")
|
||||
else:
|
||||
warnings.append(translation_warning(path, root, difference))
|
||||
if fresh and translated.inline_code != original.inline_code:
|
||||
changed = sorted((translated.inline_code - original.inline_code) + (original.inline_code - translated.inline_code))
|
||||
warnings.append(translation_warning(
|
||||
path, root, f"inline code differs from the English page: {', '.join(repr(text) for text in changed[:5])}",
|
||||
))
|
||||
|
||||
if language in ("ja", "zh-hans", "zh-hant"):
|
||||
for text in translated.prose:
|
||||
for match in CJK_GAP.finditer(text):
|
||||
errors.append(
|
||||
f"{label}: whitespace between {match.group(1)!r} and {match.group(2)!r} renders as a gap; "
|
||||
"keep CJK text on one line without spaces"
|
||||
)
|
||||
|
||||
for reference in page.references:
|
||||
url = urlsplit(reference)
|
||||
if url.scheme or url.netloc or not url.path or reference.startswith("/"):
|
||||
continue
|
||||
target = (path.parent / unquote(url.path)).resolve()
|
||||
if target.is_dir():
|
||||
target /= "index.html"
|
||||
if not target.is_relative_to(site.resolve()):
|
||||
continue
|
||||
target_language, target_english = page_language(site.resolve(), target)
|
||||
if (
|
||||
target_language == "en"
|
||||
and target_english != english
|
||||
and state.translations.get((language, target_english)) == "reviewed"
|
||||
):
|
||||
warnings.append(translation_warning(
|
||||
path, root, f"links to the English {target_english}; link to its reviewed translation instead",
|
||||
))
|
||||
|
||||
english_strings = state.locales["en"]["strings"]
|
||||
for code in LANGUAGES:
|
||||
if code == "en" or not any(key[0] == code for key in state.translations):
|
||||
continue
|
||||
locale = state.locales[code]
|
||||
same = sorted(
|
||||
key for key, value in locale["strings"].items()
|
||||
if value == english_strings[key] and key not in locale.get("sameAsEnglish", [])
|
||||
)
|
||||
if same:
|
||||
warnings.append((f"website/locales/{code}.json", f"UI strings still in English: {', '.join(same)}"))
|
||||
return errors, warnings
|
||||
|
||||
|
||||
def report_warnings(warnings):
|
||||
"""Print warnings, as GitHub annotations and a job summary when running in Actions."""
|
||||
for file, message in warnings:
|
||||
print(f"Warning: {file}: {message}")
|
||||
if os.environ.get("GITHUB_ACTIONS") != "true" or not warnings:
|
||||
return
|
||||
for file, message in warnings:
|
||||
print(f"::warning file={file}::{message}")
|
||||
summary = os.environ.get("GITHUB_STEP_SUMMARY")
|
||||
if summary:
|
||||
with open(summary, "a", encoding="utf-8") as output:
|
||||
output.write("### Website warnings\n\n")
|
||||
output.writelines(f"- `{file}`: {message}\n" for file, message in warnings)
|
||||
|
||||
|
||||
def check_publisher(root):
|
||||
"""Detect a second Pages action that could replace the website."""
|
||||
expected = root / ".github/workflows/website-pages.yml"
|
||||
@@ -404,10 +611,16 @@ def main():
|
||||
errors.extend(check_example_archive(root / "website/public"))
|
||||
errors.extend(check_publisher(root))
|
||||
errors.extend(check_repository_links(root))
|
||||
translation_errors, warnings = check_translations(root, parse_pages(root / "website/public"))
|
||||
errors.extend(translation_errors)
|
||||
try:
|
||||
sync_pages(root, check=True)
|
||||
for path in sync_pages(root, check=True):
|
||||
warnings.append(translation_warning(
|
||||
path, root, "the out-of-date notice needs refreshing; run python3 scripts/website.py sync",
|
||||
))
|
||||
except (OSError, ValueError, KeyError) as error:
|
||||
errors.append(str(error))
|
||||
report_warnings(warnings)
|
||||
if errors:
|
||||
print("Website checks failed:\n" + "\n".join(errors), file=sys.stderr)
|
||||
return 1
|
||||
|
||||
+433
-28
@@ -1,26 +1,53 @@
|
||||
"""Maintain shared HTML and run the static website's contributor commands."""
|
||||
|
||||
import argparse
|
||||
from collections import namedtuple
|
||||
from functools import partial
|
||||
from hashlib import sha256
|
||||
from html import escape
|
||||
from html.parser import HTMLParser
|
||||
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
|
||||
import json
|
||||
from pathlib import Path, PurePosixPath
|
||||
import posixpath
|
||||
import re
|
||||
from string import Template
|
||||
import subprocess
|
||||
import sys
|
||||
from textwrap import indent
|
||||
from urllib.parse import quote, urlsplit
|
||||
from urllib.parse import quote, urlsplit, urlunsplit
|
||||
|
||||
|
||||
SITE_ORIGIN = "https://rea.tools"
|
||||
NOTES_FIXTURES = {"examples/notes-electron/index.html", "examples/notes-web/index.html"}
|
||||
# Each label is a key in website/locales/<language>.json.
|
||||
NAVIGATION = (
|
||||
("Showcases", "showcase/"),
|
||||
("Blog", "blog/"),
|
||||
("Get started", "get-started/"),
|
||||
("Guides", "guides/"),
|
||||
("FAQ", "faq/"),
|
||||
("navShowcases", "showcase/"),
|
||||
("navBlog", "blog/"),
|
||||
("navGetStarted", "get-started/"),
|
||||
("navGuides", "guides/"),
|
||||
("navFaq", "faq/"),
|
||||
)
|
||||
Language = namedtuple("Language", "tag name og_locale")
|
||||
# English stays at the root; every other language lives under its directory.
|
||||
# The order is the language menu's order.
|
||||
LANGUAGES = {
|
||||
"en": Language("en", "English", "en_US"),
|
||||
"zh-hans": Language("zh-Hans", "简体中文", "zh_CN"),
|
||||
"zh-hant": Language("zh-Hant", "繁體中文", "zh_TW"),
|
||||
"ja": Language("ja", "日本語", "ja_JP"),
|
||||
"ko": Language("ko", "한국어", "ko_KR"),
|
||||
"de": Language("de", "Deutsch", "de_DE"),
|
||||
"fr": Language("fr", "Français", "fr_FR"),
|
||||
}
|
||||
TRANSLATION_STATUSES = ("draft", "reviewed")
|
||||
TRANSLATION_RECORD = re.compile(r"<!-- website:translation((?:\s+[\w-]+=\"[^\"]*\")*)\s*-->")
|
||||
SHARED_REGION = re.compile(r"<!-- website:([\w-]+):start -->.*?<!-- website:\1:end -->", re.S)
|
||||
NOTICE_START = " <!-- website:translation-notice:start -->\n"
|
||||
NOTICE_END = " <!-- website:translation-notice:end -->"
|
||||
GLOBE_PATH = (
|
||||
"M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18Z M3.6 9h16.8 M3.6 15h16.8 "
|
||||
"M12 3c2.4 2.5 3.6 5.5 3.6 9s-1.2 6.5-3.6 9c-2.4-2.5-3.6-5.5-3.6-9s1.2-6.5 3.6-9Z"
|
||||
)
|
||||
|
||||
|
||||
@@ -75,10 +102,14 @@ class PageMetadata(HTMLParser):
|
||||
self.titles[-1] += data
|
||||
|
||||
|
||||
def file_route(relative):
|
||||
"""Map a site-relative HTML file to its public route."""
|
||||
return relative.removesuffix("index.html") if PurePosixPath(relative).name == "index.html" else relative
|
||||
|
||||
|
||||
def page_route(site, path):
|
||||
"""Map an HTML file to its public route without a separate page registry."""
|
||||
route = path.relative_to(site).as_posix()
|
||||
return route.removesuffix("index.html") if path.name == "index.html" else route
|
||||
return file_route(path.relative_to(site).as_posix())
|
||||
|
||||
|
||||
def page_url(site, path):
|
||||
@@ -86,30 +117,227 @@ def page_url(site, path):
|
||||
return f"{SITE_ORIGIN}/{quote(page_route(site, path), safe='/')}"
|
||||
|
||||
|
||||
def shared_blocks(root, path, source):
|
||||
def page_language(site, path):
|
||||
"""Return a page's language directory and the site-relative file of its English source."""
|
||||
relative = path.relative_to(site).as_posix()
|
||||
first, separator, rest = relative.partition("/")
|
||||
if separator and first in LANGUAGES and first != "en":
|
||||
return first, rest
|
||||
return "en", relative
|
||||
|
||||
|
||||
def load_locales(root):
|
||||
"""Read the UI strings for every language and require the same keys as English."""
|
||||
directory = root / "website/locales"
|
||||
locales = {}
|
||||
for code in LANGUAGES:
|
||||
path = directory / f"{code}.json"
|
||||
try:
|
||||
locale = json.loads(path.read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError) as error:
|
||||
raise ValueError(f"website/locales/{code}.json: cannot read UI strings: {error}") from error
|
||||
locales[code] = locale
|
||||
expected = set(locales["en"]["strings"])
|
||||
for code, locale in locales.items():
|
||||
label = f"website/locales/{code}.json"
|
||||
strings = locale.get("strings")
|
||||
if not isinstance(strings, dict) or set(strings) != expected:
|
||||
missing = sorted(expected - set(strings or {}))
|
||||
extra = sorted(set(strings or {}) - expected)
|
||||
raise ValueError(f"{label}: strings must match en.json (missing {missing}, extra {extra})")
|
||||
if any(not isinstance(value, str) or not value.strip() for value in strings.values()):
|
||||
raise ValueError(f"{label}: every UI string must be nonempty text")
|
||||
stars = locale.get("githubStars")
|
||||
if not isinstance(stars, dict) or "other" not in stars or not set(stars) <= {"zero", "one", "two", "few", "many", "other"}:
|
||||
raise ValueError(f"{label}: githubStars needs an 'other' label and CLDR plural categories only")
|
||||
if any("{count}" not in value for value in stars.values()):
|
||||
raise ValueError(f"{label}: every githubStars label needs a {{count}} placeholder")
|
||||
if "{link}" not in strings["staleNotice"]:
|
||||
raise ValueError(f"{label}: staleNotice needs a {{link}} placeholder")
|
||||
same = locale.get("sameAsEnglish", [])
|
||||
if not isinstance(same, list) or not set(same) <= expected:
|
||||
raise ValueError(f"{label}: sameAsEnglish must list UI string keys")
|
||||
return locales
|
||||
|
||||
|
||||
def translation_record(source):
|
||||
"""Return the attributes of a translation's provenance comment, or None."""
|
||||
records = TRANSLATION_RECORD.findall(source)
|
||||
if len(records) != 1:
|
||||
return None
|
||||
return dict(re.findall(r'([\w-]+)="([^"]*)"', records[0]))
|
||||
|
||||
|
||||
def copy_targets(source):
|
||||
"""Return the IDs referenced by copy buttons, in page order."""
|
||||
return list(dict.fromkeys(re.findall(r'\bdata-copy="([^"]+)"', source)))
|
||||
|
||||
|
||||
def code_block(identifier):
|
||||
"""Match a code element by ID, capturing its opening tag, contents and end tag."""
|
||||
return re.compile(rf'(<code\b[^>]*\bid="{re.escape(identifier)}"[^>]*>)(.*?)(</code>)', re.S)
|
||||
|
||||
|
||||
def synced_code_ids(source):
|
||||
"""Return the copy targets that are code blocks; translations take them from English."""
|
||||
return [identifier for identifier in copy_targets(source) if code_block(identifier).search(source)]
|
||||
|
||||
|
||||
def source_digest(source):
|
||||
"""Hash an English page's translatable content.
|
||||
|
||||
Shared regions and copied code blocks are left out, so template edits and
|
||||
command-only changes do not mark translations out of date.
|
||||
"""
|
||||
content = SHARED_REGION.sub("", source)
|
||||
for identifier in synced_code_ids(source):
|
||||
content = code_block(identifier).sub(r"\1\3", content)
|
||||
return sha256(" ".join(content.split()).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def sync_code_blocks(english, source, label):
|
||||
"""Copy every synced code block's contents from the English source, matched by ID."""
|
||||
for identifier in synced_code_ids(english):
|
||||
contents = code_block(identifier).search(english).group(2)
|
||||
pattern = code_block(identifier)
|
||||
if len(pattern.findall(source)) != 1:
|
||||
raise ValueError(f"{label}: needs one <code id=\"{identifier}\"> block copied from the English page")
|
||||
source = pattern.sub(lambda match: match.group(1) + contents + match.group(3), source)
|
||||
return source
|
||||
|
||||
|
||||
class SiteState:
|
||||
"""Read the locales and every translation's status once for a sync or check."""
|
||||
|
||||
def __init__(self, root):
|
||||
self.root = root
|
||||
self.site = root / "website/public"
|
||||
self.locales = load_locales(root)
|
||||
self.translations = {}
|
||||
for path in sorted(self.site.rglob("*.html")):
|
||||
language, english = page_language(self.site, path)
|
||||
if language != "en":
|
||||
record = translation_record(path.read_text(encoding="utf-8")) or {}
|
||||
self.translations[(language, english)] = record.get("status")
|
||||
|
||||
def linkable(self, language, english, from_draft=False):
|
||||
"""Report whether other pages may link to this language's version of a page."""
|
||||
if language == "en":
|
||||
return (self.site / english).is_file()
|
||||
status = self.translations.get((language, english))
|
||||
return status == "reviewed" or (from_draft and status == "draft")
|
||||
|
||||
def alternates(self, english):
|
||||
"""Return the languages whose versions of a page join its hreflang cluster."""
|
||||
return [code for code in LANGUAGES if code == "en" or self.translations.get((code, english)) == "reviewed"]
|
||||
|
||||
|
||||
def language_url(language, english):
|
||||
"""Return the canonical URL of one language's version of a page."""
|
||||
prefix = "" if language == "en" else f"{language}/"
|
||||
return f"{SITE_ORIGIN}/{quote(prefix + file_route(english), safe='/')}"
|
||||
|
||||
|
||||
def shared_blocks(root, path, source, state=None):
|
||||
"""Render shared regions while keeping the page's body and metadata authored."""
|
||||
site = root / "website/public"
|
||||
state = state or SiteState(root)
|
||||
site = state.site
|
||||
metadata = PageMetadata()
|
||||
metadata.feed(source)
|
||||
for name, values in (("title", metadata.titles), ("description", metadata.descriptions)):
|
||||
if len(values) != 1 or not values[0].strip():
|
||||
raise ValueError(f"{path.relative_to(site)}: needs one nonempty head {name}")
|
||||
language, english = page_language(site, path)
|
||||
strings = state.locales[language]["strings"]
|
||||
depth = len(path.relative_to(site).parent.parts)
|
||||
base = "../" * depth or "./"
|
||||
route = page_route(site, path)
|
||||
route = file_route(english)
|
||||
draft = language != "en" and state.translations.get((language, english)) == "draft"
|
||||
|
||||
def href(target_language, target):
|
||||
prefix = "" if target_language == "en" else f"{target_language}/"
|
||||
return base + file_route(prefix + target)
|
||||
|
||||
def localized(target):
|
||||
"""Prefer this language's version of a target page, else the English page."""
|
||||
if language != "en" and state.linkable(language, target, from_draft=draft):
|
||||
return language, href(language, target)
|
||||
return "en", href("en", target)
|
||||
|
||||
links = []
|
||||
for label, destination in NAVIGATION:
|
||||
for key, destination in NAVIGATION:
|
||||
target_language, url = localized(destination + "index.html")
|
||||
attributes = ' class="nav-start"' if destination == "get-started/" else ""
|
||||
if route.startswith(destination):
|
||||
attributes += ' aria-current="page"'
|
||||
links.append(f' <a href="{base}{destination}"{attributes}>{label}</a>')
|
||||
badge = ""
|
||||
if target_language != language:
|
||||
attributes += ' hreflang="en"'
|
||||
badge = '<span class="nav-badge" lang="en">EN</span>'
|
||||
links.append(f' <a href="{url}"{attributes}>{escape(strings[key])}{badge}</a>')
|
||||
|
||||
entries = []
|
||||
for code, details in LANGUAGES.items():
|
||||
if code == language or state.linkable(code, english):
|
||||
url = href(code, english)
|
||||
elif state.linkable(code, "index.html"):
|
||||
url = href(code, "index.html")
|
||||
else:
|
||||
continue
|
||||
current = ' aria-current="true"' if code == language else ""
|
||||
entries.append(
|
||||
f' <li><a href="{url}" hreflang="{details.tag}" lang="{details.tag}"{current}>{details.name}</a></li>'
|
||||
)
|
||||
language_menu = ""
|
||||
if len(entries) > 1:
|
||||
language_menu = "\n".join((
|
||||
"",
|
||||
' <details class="language-menu">',
|
||||
" <summary>",
|
||||
' <svg width="18" height="18" viewBox="0 0 24 24" aria-hidden="true" focusable="false">',
|
||||
f' <path fill="none" stroke="currentColor" stroke-width="1.6" d="{GLOBE_PATH}" />',
|
||||
" </svg>",
|
||||
f' <span class="sr-only">{escape(strings["language"])}: </span>'
|
||||
f'<span class="language-current">{LANGUAGES[language].name}</span>',
|
||||
" </summary>",
|
||||
' <ul class="language-list">',
|
||||
*entries,
|
||||
" </ul>",
|
||||
" </details>",
|
||||
))
|
||||
|
||||
members = [] if draft else state.alternates(english)
|
||||
hreflang = ""
|
||||
locale_alternates = ""
|
||||
if len(members) > 1:
|
||||
for code in [*members, "x-default"]:
|
||||
tag = LANGUAGES[code].tag if code != "x-default" else code
|
||||
url = language_url(code if code != "x-default" else "en", english)
|
||||
hreflang += f'\n<!-- prettier-ignore -->\n<link rel="alternate" hreflang="{tag}" href="{escape(url, quote=True)}" />'
|
||||
for code in members:
|
||||
if code != language:
|
||||
locale_alternates += (
|
||||
f'\n<!-- prettier-ignore -->\n<meta property="og:locale:alternate" content="{LANGUAGES[code].og_locale}" />'
|
||||
)
|
||||
|
||||
labels = "".join(
|
||||
f'\n data-label-{category}="{escape(label, quote=True)}"'
|
||||
for category, label in state.locales[language]["githubStars"].items()
|
||||
)
|
||||
values = {
|
||||
"base": base,
|
||||
"brand": localized("index.html")[1],
|
||||
"navigation": "\n" + "\n".join(links) + "\n ",
|
||||
"language_menu": language_menu,
|
||||
"canonical": escape(page_url(site, path), quote=True),
|
||||
"hreflang": hreflang,
|
||||
"og_locale": LANGUAGES[language].og_locale,
|
||||
"og_locale_alternates": locale_alternates,
|
||||
"origin": SITE_ORIGIN,
|
||||
"title": escape(metadata.titles[0].strip(), quote=True),
|
||||
"description": escape(metadata.descriptions[0].strip(), quote=True),
|
||||
"github_star_labels": labels,
|
||||
**{f"t_{key}": escape(value, quote=True) for key, value in strings.items()},
|
||||
}
|
||||
templates = root / "website/templates"
|
||||
return {
|
||||
@@ -118,35 +346,89 @@ def shared_blocks(root, path, source):
|
||||
}
|
||||
|
||||
|
||||
def translation_notice(state, path, english_source, record):
|
||||
"""Render the stale-translation notice, or nothing while the source hash matches."""
|
||||
if record is None or record.get("source-sha256") == source_digest(english_source):
|
||||
return ""
|
||||
language, english = page_language(state.site, path)
|
||||
strings = state.locales[language]["strings"]
|
||||
depth = len(path.relative_to(state.site).parent.parts)
|
||||
link = (
|
||||
f'<a href="{"../" * depth}{file_route(english)}" hreflang="en">'
|
||||
f'{escape(strings["staleNoticeLink"])}</a>'
|
||||
)
|
||||
message = escape(strings["staleNotice"]).replace("{link}", link)
|
||||
return f' <!-- prettier-ignore -->\n <p class="translation-notice" role="note">{message}</p>\n'
|
||||
|
||||
|
||||
def replace_region(source, start, end, block, label, name):
|
||||
"""Replace the contents of one marked region."""
|
||||
if source.count(start) != 1 or source.count(end) != 1:
|
||||
raise ValueError(f"{label}: needs one {name} region; use new-page or translate for a new page")
|
||||
before, _, remaining = source.partition(start)
|
||||
_, found, after = remaining.partition(end)
|
||||
if not found:
|
||||
raise ValueError(f"{label}: {name} region is out of order")
|
||||
return before + start + block + end + after
|
||||
|
||||
|
||||
def region_contents(source, start, end):
|
||||
"""Return the current contents of a marked region."""
|
||||
return source.partition(start)[2].partition(end)[0]
|
||||
|
||||
|
||||
def sync_pages(root, check=False):
|
||||
"""Update shared regions, or reject drift without changing any authored file."""
|
||||
site = root / "website/public"
|
||||
"""Update shared regions, or reject drift without changing any authored file.
|
||||
|
||||
Returns the pages that changed. With check=True, structural drift raises, so
|
||||
the returned pages are translations whose only drift is the stale notice;
|
||||
an out-of-date translation is a warning rather than a failure.
|
||||
"""
|
||||
state = SiteState(root)
|
||||
site = state.site
|
||||
changes = []
|
||||
notices = []
|
||||
for path in sorted(site.rglob("*.html")):
|
||||
if path.relative_to(site).as_posix() in NOTES_FIXTURES:
|
||||
continue
|
||||
label = path.relative_to(site).as_posix()
|
||||
original = path.read_text(encoding="utf-8")
|
||||
source = original
|
||||
for name, block in shared_blocks(root, path, source).items():
|
||||
start = f" <!-- website:{name}:start -->\n"
|
||||
end = f" <!-- website:{name}:end -->"
|
||||
if source.count(start) != 1 or source.count(end) != 1:
|
||||
raise ValueError(f"{path.relative_to(site)}: needs one {name} region; use new-page for a new reading page")
|
||||
before, _, remaining = source.partition(start)
|
||||
_, found, after = remaining.partition(end)
|
||||
if not found:
|
||||
raise ValueError(f"{path.relative_to(site)}: {name} region is out of order")
|
||||
source = before + start + block + end + after
|
||||
language, english = page_language(site, path)
|
||||
english_source = None
|
||||
if language != "en":
|
||||
english_path = site / english
|
||||
if not english_path.is_file():
|
||||
raise ValueError(f"{label}: translates {english}, which does not exist")
|
||||
english_source = english_path.read_text(encoding="utf-8")
|
||||
source = sync_code_blocks(english_source, source, label)
|
||||
for name, block in shared_blocks(root, path, source, state).items():
|
||||
source = replace_region(
|
||||
source, f" <!-- website:{name}:start -->\n", f" <!-- website:{name}:end -->", block, label, name
|
||||
)
|
||||
if language != "en":
|
||||
notice = translation_notice(state, path, english_source, translation_record(source))
|
||||
structural = replace_region(
|
||||
source, NOTICE_START, NOTICE_END, region_contents(original, NOTICE_START, NOTICE_END), label,
|
||||
"translation-notice",
|
||||
)
|
||||
source = replace_region(source, NOTICE_START, NOTICE_END, notice, label, "translation-notice")
|
||||
if structural == original and source != original:
|
||||
notices.append((path, source))
|
||||
continue
|
||||
if source != original:
|
||||
changes.append((path, source))
|
||||
if check and changes:
|
||||
names = ", ".join(str(path.relative_to(site)) for path, _ in changes)
|
||||
raise ValueError(f"Shared HTML is stale: {names}. Run python3 scripts/website.py sync and commit the updated pages.")
|
||||
if not check:
|
||||
for path, source in changes:
|
||||
for path, source in changes + notices:
|
||||
path.write_text(source, encoding="utf-8")
|
||||
print(f"{'Checked' if check else 'Synced'} shared HTML ({len(changes)} pages changed).")
|
||||
return [path for path, _ in changes]
|
||||
if check:
|
||||
print(f"Checked shared HTML ({len(notices)} translation notices to refresh).")
|
||||
else:
|
||||
print(f"Synced shared HTML ({len(changes) + len(notices)} pages changed).")
|
||||
return [path for path, _ in (notices if check else changes + notices)]
|
||||
|
||||
|
||||
def new_page(root, route, title, description):
|
||||
@@ -154,6 +436,8 @@ def new_page(root, route, title, description):
|
||||
parts = PurePosixPath(route)
|
||||
if not route or parts.is_absolute() or ".." in parts.parts or "\\" in route or parts.suffix:
|
||||
raise ValueError("Use a relative directory route, such as blog/my-article.")
|
||||
if parts.parts[0] in LANGUAGES:
|
||||
raise ValueError("Create the English page first, then use translate for another language.")
|
||||
site = root / "website/public"
|
||||
path = site.joinpath(*parts.parts, "index.html")
|
||||
if not path.resolve().is_relative_to(site.resolve()):
|
||||
@@ -174,6 +458,118 @@ def new_page(root, route, title, description):
|
||||
return path
|
||||
|
||||
|
||||
def relocate_references(source, english, language, state):
|
||||
"""Rewrite relative references for the translation's directory.
|
||||
|
||||
Pages that already have a version in this language link to it; everything
|
||||
else keeps pointing at the English page or asset.
|
||||
"""
|
||||
english_directory = posixpath.dirname(english)
|
||||
translation_directory = posixpath.join(language, english_directory)
|
||||
|
||||
def rewrite(match):
|
||||
value = match.group(2)
|
||||
url = urlsplit(value)
|
||||
if not value or url.scheme or url.netloc or value.startswith(("#", "/")):
|
||||
return match.group(0)
|
||||
target = posixpath.normpath(posixpath.join(english_directory, url.path))
|
||||
directory = url.path.endswith("/") or target == "."
|
||||
if directory:
|
||||
page = "index.html" if target == "." else f"{target}/index.html"
|
||||
if (language, page) in state.translations:
|
||||
target = posixpath.normpath(posixpath.join(language, target))
|
||||
relative = posixpath.relpath(target, translation_directory or ".")
|
||||
if directory:
|
||||
relative = "./" if relative == "." else relative + "/"
|
||||
return f'{match.group(1)}="{urlunsplit(("", "", relative, url.query, url.fragment))}"'
|
||||
|
||||
return re.sub(r'\b(href|src)="([^"]*)"', rewrite, source)
|
||||
|
||||
|
||||
def new_translation(root, language, route):
|
||||
"""Create a draft translation of an English page, ready to be translated in place."""
|
||||
if language not in LANGUAGES or language == "en":
|
||||
raise ValueError(f"Choose one of: {', '.join(code for code in LANGUAGES if code != 'en')}.")
|
||||
route = route.strip("/")
|
||||
parts = PurePosixPath(route) if route not in ("", ".") else PurePosixPath()
|
||||
if parts.is_absolute() or ".." in parts.parts or "\\" in route or parts.suffix:
|
||||
raise ValueError("Use the English page's directory route, such as get-started, or / for the home page.")
|
||||
if parts.parts and parts.parts[0] in LANGUAGES:
|
||||
raise ValueError("Name the English route, without a language directory.")
|
||||
english = PurePosixPath(*parts.parts, "index.html").as_posix()
|
||||
state = SiteState(root)
|
||||
site = state.site
|
||||
source_path = site / english
|
||||
if not source_path.is_file() or english in NOTES_FIXTURES:
|
||||
raise ValueError(f"No English page to translate at {english}.")
|
||||
path = site / language / english
|
||||
if path.exists():
|
||||
raise ValueError(f"Translation already exists: {path.relative_to(site)}")
|
||||
source = source_path.read_text(encoding="utf-8")
|
||||
if source.count('<html lang="en">') != 1 or source.count(" <!-- website:sharing:start -->\n") != 1:
|
||||
raise ValueError(f"{english}: needs <html lang=\"en\"> and one sharing region")
|
||||
main = re.search(r"^ {4}<main\b[^>]*>\n", source, re.M)
|
||||
if main is None:
|
||||
raise ValueError(f"{english}: needs a <main> element on its own line")
|
||||
source = source.replace('<html lang="en">', f'<html lang="{LANGUAGES[language].tag}">')
|
||||
source = relocate_references(source, english, language, state)
|
||||
record = (
|
||||
f' <!-- website:translation source-sha256="{source_digest(source_path.read_text(encoding="utf-8"))}" '
|
||||
'status="draft" -->\n'
|
||||
)
|
||||
robots = "" if '<meta name="robots"' in source else ' <meta name="robots" content="noindex" />\n'
|
||||
source = source.replace(" <!-- website:sharing:start -->\n", robots + record + " <!-- website:sharing:start -->\n")
|
||||
main = re.search(r"^ {4}<main\b[^>]*>\n", source, re.M)
|
||||
source = source[: main.end()] + NOTICE_START + NOTICE_END + "\n" + source[main.end():]
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(source, encoding="utf-8")
|
||||
sync_pages(root)
|
||||
print(
|
||||
f"Created {path.relative_to(root)} as a noindex draft. Translate its text in place following "
|
||||
"website/translation.md, then run python3 scripts/website.py check."
|
||||
)
|
||||
return path
|
||||
|
||||
|
||||
def translation_report(root, language=None):
|
||||
"""Describe each translation's review status, freshness and remaining review items."""
|
||||
state = SiteState(root)
|
||||
site = state.site
|
||||
lines = []
|
||||
for (code, english), status in sorted(state.translations.items()):
|
||||
if language and code != language:
|
||||
continue
|
||||
path = site / code / english
|
||||
source = path.read_text(encoding="utf-8")
|
||||
record = translation_record(source) or {}
|
||||
english_path = site / english
|
||||
current = source_digest(english_path.read_text(encoding="utf-8")) if english_path.is_file() else None
|
||||
fresh = record.get("source-sha256") == current
|
||||
reviewed = f" on {record['reviewed']}" if record.get("reviewed") else ""
|
||||
lines.append(f"{code}/{file_route(english) or '(home)'}: {status or 'no record'}{reviewed}, "
|
||||
f"{'up to date' if fresh else 'English source changed'}")
|
||||
if not fresh and current:
|
||||
lines.append(f" after updating the translation, record source-sha256=\"{current}\"")
|
||||
if status != "reviewed":
|
||||
for system, text in re.findall(r'<(?:em|span|strong|kbd)\b[^>]*\bdata-os-ui="([^"]+)"[^>]*>(.*?)</', source, re.S):
|
||||
lines.append(f" confirm on {system}: {' '.join(text.split())}")
|
||||
english_strings = state.locales["en"]["strings"]
|
||||
for code in LANGUAGES:
|
||||
if code == "en" or (language and code != language):
|
||||
continue
|
||||
if not any(key[0] == code for key in state.translations):
|
||||
continue
|
||||
locale = state.locales[code]
|
||||
same = sorted(
|
||||
key for key, value in locale["strings"].items()
|
||||
if value == english_strings[key] and key not in locale.get("sameAsEnglish", [])
|
||||
)
|
||||
if same:
|
||||
lines.append(f"{code}: UI strings still in English: {', '.join(same)}")
|
||||
print("\n".join(lines) or "No translated pages.")
|
||||
return lines
|
||||
|
||||
|
||||
def run_script(root, name, arguments=()):
|
||||
"""Use the active Python environment for the existing preparation and checks."""
|
||||
subprocess.run([sys.executable, str(root / "scripts" / name), *arguments], cwd=root, check=True)
|
||||
@@ -215,6 +611,11 @@ def main():
|
||||
create.add_argument("route")
|
||||
create.add_argument("--title", required=True)
|
||||
create.add_argument("--description", required=True)
|
||||
translate = commands.add_parser("translate", help="Create a draft translation of an English page")
|
||||
translate.add_argument("language", choices=[code for code in LANGUAGES if code != "en"])
|
||||
translate.add_argument("route", help="The English page's directory route, or / for the home page")
|
||||
report = commands.add_parser("translations", help="List translation status, freshness and review items")
|
||||
report.add_argument("--lang", choices=[code for code in LANGUAGES if code != "en"])
|
||||
serve = commands.add_parser("serve", help="Prepare and preview the static site")
|
||||
serve.add_argument("--port", type=int, default=4173)
|
||||
serve.add_argument("--base-path", choices=("/", "/rea/"), default="/")
|
||||
@@ -223,6 +624,10 @@ def main():
|
||||
try:
|
||||
if args.command == "new-page":
|
||||
new_page(root, args.route, args.title, args.description)
|
||||
elif args.command == "translate":
|
||||
new_translation(root, args.language, args.route)
|
||||
elif args.command == "translations":
|
||||
translation_report(root, args.lang)
|
||||
elif args.command == "sync":
|
||||
sync_pages(root, check=args.check)
|
||||
elif args.command == "check":
|
||||
|
||||
+6
-2
@@ -9,10 +9,14 @@ website content, layout or figures. Use [figures.md](figures.md) and `evidence/`
|
||||
for asset notes and the source of case-study claims.
|
||||
|
||||
- Write English, direct headings and concrete instructions. Each paragraph
|
||||
should explain a new fact or action.
|
||||
should explain a new fact or action. Translated pages follow
|
||||
[translation.md](translation.md): create them with `translate`, keep their
|
||||
structure and copied code blocks in step with English, and refresh a
|
||||
translation's source hash only after updating its text.
|
||||
- Reuse the shared styles, prompts, figures and code-step components. Keep a
|
||||
case study focused on one question, with further examples in native details.
|
||||
- Edit shared header, footer and sharing markup in `templates/`; run
|
||||
- Edit shared header, footer and sharing markup in `templates/` and their text
|
||||
in `locales/`; run
|
||||
`python3 scripts/website.py sync` and commit the rendered regions with their
|
||||
templates. Keep page bodies outside the marked regions. Author each title and
|
||||
description once; derive sharing fields and canonicals from them. Use
|
||||
|
||||
+9
-3
@@ -4,7 +4,9 @@
|
||||
>
|
||||
> — N0zoM1z0
|
||||
|
||||
An English static website with explanatory figures, worked guides and Aegis, DX-Ball, Notion, TH04 and CTF investigations.
|
||||
A static website with explanatory figures, worked guides and Aegis, DX-Ball, Notion, TH04 and CTF investigations.
|
||||
It is written in English; the home page, Get started, the Guides index and the FAQ are
|
||||
also translated, as described in [translation.md](translation.md).
|
||||
The public files are in `website/public/`. The site uses HTML, CSS and small
|
||||
scripts for copying code, following code comparisons and playing the dinosaur
|
||||
speed reconstruction. The scripts contain no reader-facing text: copy messages
|
||||
@@ -49,8 +51,10 @@ applies to every page.
|
||||
| ------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| Page text, examples or figures | The page's HTML outside the marked shared regions | `python3 scripts/website.py check` |
|
||||
| Search title or description | The page's `<title>` and first description meta tag | `python3 scripts/website.py sync`, then `check` |
|
||||
| Main navigation | `NAVIGATION` in `scripts/website.py` | `sync`, then `check` |
|
||||
| Main navigation | `NAVIGATION` in `scripts/website.py` and labels in `locales/` | `sync`, then `check` |
|
||||
| Header, social links or footer | `templates/header.html.tmpl` or `templates/footer.html.tmpl` | `sync`, then `check` |
|
||||
| Shared UI text in a language | `locales/<language>.json` | `sync`, then `check` |
|
||||
| A translated page | See [translation.md](translation.md) | `translate`, then `check` |
|
||||
| Shared link previews | `templates/sharing.html.tmpl` or `public/assets/social-card.svg` | `sync`, then `check` |
|
||||
|
||||
Create a reading page with:
|
||||
@@ -465,7 +469,9 @@ See Cloudflare's [GitHub Actions authentication instructions](https://developers
|
||||
The default `both` target checks that both secrets are present before preparing
|
||||
a release. Cloudflare deploys first; GitHub Pages deploys after that step succeeds.
|
||||
|
||||
Preparation adds `deployment.json` with the workflow's commit SHA. Cloudflare
|
||||
After the checks pass, preparation runs `sync` so a translation whose English
|
||||
page changed is published with its out-of-date notice, then adds
|
||||
`deployment.json` with the workflow's commit SHA. Cloudflare
|
||||
receives the extracted Pages artifact through Wrangler's explicit assets path;
|
||||
the production environment disables Wrangler's preview custom build, so deployment
|
||||
uses the prepared artifact directly. The workflow then
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"one": "REA on GitHub ({count} star)",
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"one": "REA on GitHub ({count} star)",
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"one": "REA on GitHub ({count} star)",
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"strings": {
|
||||
"skipLink": "Skip to content",
|
||||
"home": "REA home",
|
||||
"mainNavigation": "Main navigation",
|
||||
"navShowcases": "Showcases",
|
||||
"navBlog": "Blog",
|
||||
"navGetStarted": "Get started",
|
||||
"navGuides": "Guides",
|
||||
"navFaq": "FAQ",
|
||||
"language": "Language",
|
||||
"github": "REA on GitHub",
|
||||
"discord": "Join REA on Discord",
|
||||
"followRea": "Follow REA on X",
|
||||
"source": "Source",
|
||||
"license": "MIT license",
|
||||
"community": "Join the community",
|
||||
"followUs": "Follow us on X",
|
||||
"copied": "Copied",
|
||||
"selected": "Selected",
|
||||
"statusCopied": "Code copied to clipboard.",
|
||||
"statusSelected": "Code selected. Use your keyboard to copy it.",
|
||||
"backToTop": "Back to top",
|
||||
"top": "Top",
|
||||
"imageAlt": "REA — Find out how software works. Reverse engineering with your coding agent.",
|
||||
"staleNotice": "The English page has changed since this translation. {link}",
|
||||
"staleNoticeLink": "Read the English version."
|
||||
},
|
||||
"githubStars": {
|
||||
"other": "REA on GitHub ({count} stars)"
|
||||
},
|
||||
"sameAsEnglish": []
|
||||
}
|
||||
@@ -6,9 +6,11 @@
|
||||
--soft: #f4f6f8;
|
||||
--accent: #294f82;
|
||||
--page: #ffffff;
|
||||
--font-sans:
|
||||
-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
|
||||
--font-mono: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
|
||||
/* Translated pages extend these stacks with fonts for their script. */
|
||||
--font-latin: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial;
|
||||
--font-code: "SFMono-Regular", Consolas, "Liberation Mono";
|
||||
--font-sans: var(--font-latin), sans-serif;
|
||||
--font-mono: var(--font-code), monospace;
|
||||
font-family: var(--font-sans);
|
||||
font-synthesis: none;
|
||||
text-rendering: optimizeLegibility;
|
||||
@@ -2487,3 +2489,176 @@ pre code {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
/* Translated pages. Latin text keeps the site's fonts, then each language
|
||||
names its own CJK fonts so Han characters take that language's forms. */
|
||||
:lang(en) {
|
||||
--font-sans: var(--font-latin), sans-serif;
|
||||
--font-mono: var(--font-code), monospace;
|
||||
}
|
||||
:lang(ja) {
|
||||
--font-sans:
|
||||
var(--font-latin), "Hiragino Sans", "Hiragino Kaku Gothic ProN",
|
||||
"Yu Gothic UI", Meiryo, "Noto Sans JP", "Noto Sans CJK JP", sans-serif;
|
||||
--font-mono:
|
||||
var(--font-code), "Hiragino Sans", "Yu Gothic UI", "Noto Sans JP",
|
||||
"Noto Sans CJK JP", monospace;
|
||||
}
|
||||
:lang(zh-Hans) {
|
||||
--font-sans:
|
||||
var(--font-latin), "PingFang SC", "Microsoft YaHei", "Noto Sans SC",
|
||||
"Noto Sans CJK SC", sans-serif;
|
||||
--font-mono:
|
||||
var(--font-code), "PingFang SC", "Microsoft YaHei", "Noto Sans SC",
|
||||
"Noto Sans CJK SC", monospace;
|
||||
}
|
||||
:lang(zh-Hant) {
|
||||
--font-sans:
|
||||
var(--font-latin), "PingFang TC", "Microsoft JhengHei", "Noto Sans TC",
|
||||
"Noto Sans CJK TC", sans-serif;
|
||||
--font-mono:
|
||||
var(--font-code), "PingFang TC", "Microsoft JhengHei", "Noto Sans TC",
|
||||
"Noto Sans CJK TC", monospace;
|
||||
}
|
||||
:lang(ko) {
|
||||
--font-sans:
|
||||
var(--font-latin), "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR",
|
||||
"Noto Sans CJK KR", sans-serif;
|
||||
--font-mono:
|
||||
var(--font-code), "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR",
|
||||
"Noto Sans CJK KR", monospace;
|
||||
}
|
||||
/* Resolve the stack again wherever the language changes, such as the
|
||||
language menu's names or an English badge. */
|
||||
[lang] {
|
||||
font-family: var(--font-sans);
|
||||
}
|
||||
:is(:lang(ja), :lang(ko), :lang(zh-Hans), :lang(zh-Hant))
|
||||
:is(
|
||||
h1,
|
||||
h2,
|
||||
h3,
|
||||
.brand-name,
|
||||
.home-no,
|
||||
.agent-one-prompt,
|
||||
.stats dt,
|
||||
.home-start-grid .home-setup h2
|
||||
) {
|
||||
letter-spacing: 0;
|
||||
}
|
||||
:is(:lang(ja), :lang(ko), :lang(zh-Hans), :lang(zh-Hant)) :is(h1, h2, h3) {
|
||||
line-height: 1.3;
|
||||
text-wrap: pretty;
|
||||
}
|
||||
/* CJK fonts have no italics, so emphasis uses weight instead. */
|
||||
:is(:lang(ja), :lang(ko), :lang(zh-Hans), :lang(zh-Hant)) em {
|
||||
font-style: normal;
|
||||
font-weight: 600;
|
||||
}
|
||||
:lang(ja) {
|
||||
line-break: strict;
|
||||
}
|
||||
:lang(ja) :is(h1, h2, h3) {
|
||||
word-break: auto-phrase;
|
||||
}
|
||||
:lang(ko) {
|
||||
word-break: keep-all;
|
||||
}
|
||||
:lang(de) :is(h1, h2, h3, .lede, .contents a, .button) {
|
||||
hyphens: auto;
|
||||
overflow-wrap: break-word;
|
||||
}
|
||||
|
||||
.language-menu {
|
||||
position: relative;
|
||||
}
|
||||
.language-menu summary {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
min-height: 44px;
|
||||
padding-inline: 10px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 10px;
|
||||
color: var(--muted);
|
||||
font-size: 0.875rem;
|
||||
cursor: pointer;
|
||||
list-style: none;
|
||||
}
|
||||
.language-menu summary::-webkit-details-marker {
|
||||
display: none;
|
||||
}
|
||||
.language-menu summary:hover,
|
||||
.language-menu[open] summary {
|
||||
background: var(--soft);
|
||||
color: var(--ink);
|
||||
}
|
||||
.language-menu svg {
|
||||
display: block;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
.language-list {
|
||||
position: absolute;
|
||||
top: calc(100% + 6px);
|
||||
right: 0;
|
||||
z-index: 6;
|
||||
min-width: 10rem;
|
||||
margin: 0;
|
||||
padding: 0.35rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 10px;
|
||||
background: var(--page);
|
||||
box-shadow: 0 8px 24px rgb(32 37 43 / 12%);
|
||||
list-style: none;
|
||||
}
|
||||
.language-list li + li {
|
||||
margin-top: 0;
|
||||
}
|
||||
.language-list a {
|
||||
display: block;
|
||||
padding: 0.45rem 0.7rem;
|
||||
border-radius: 6px;
|
||||
color: var(--ink);
|
||||
text-decoration: none;
|
||||
}
|
||||
.language-list a:hover {
|
||||
background: var(--soft);
|
||||
}
|
||||
.language-list a[aria-current="true"] {
|
||||
font-weight: 600;
|
||||
}
|
||||
.nav-badge {
|
||||
margin-left: 0.3em;
|
||||
padding: 0 0.3em;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 4px;
|
||||
color: var(--muted);
|
||||
font-size: 0.65rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.04em;
|
||||
vertical-align: 0.15em;
|
||||
}
|
||||
.translation-notice {
|
||||
margin: 1.5rem 0 0;
|
||||
padding: 0.75rem 1rem;
|
||||
border-left: 3px solid var(--accent);
|
||||
background: var(--soft);
|
||||
font-size: 0.9rem;
|
||||
}
|
||||
main:not(.container) > .translation-notice {
|
||||
width: min(1080px, calc(100% - 3.5rem));
|
||||
margin-inline: auto;
|
||||
}
|
||||
@media (max-width: 640px) {
|
||||
.language-current {
|
||||
position: absolute;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
overflow: hidden;
|
||||
clip-path: inset(50%);
|
||||
white-space: nowrap;
|
||||
}
|
||||
main:not(.container) > .translation-notice {
|
||||
width: calc(100% - 2.5rem);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="REA Blog — Thoughts on Reverse Engineering" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Thoughts on reverse engineering, drawing on practical experience with REA and AI agents." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Reverse Engineering’s Industrial Revolution — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="N0zoM1z0 reflects on manual reverse engineering, Touhou reconstruction with AI agents, and how knowledge compounds across TH08, TH095 and PC-98 TH04." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Chrome Dinosaur Game: Rebuild Its Speed Rule — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Read the dinosaur game’s speed rule with REA, rebuild it, then change the speed and play." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="REA FAQ: Setup, Updates and Troubleshooting" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Answers to common REA questions: installation, updates, analysis tools, coding agents, troubleshooting and sharing examples." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Your First Reverse Engineering Investigation — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Try REA on a small Notes app. Set up your agent, ask where exported notes go, and check the CSV formatter with a sample title." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Install REA and Set Up Your Coding Agent" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Connect REA to your coding agent or inspect a local JavaScript or Electron app from the terminal. Setup, first questions and native provider guides." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Browser and Network Analysis — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Observe a Notes export with REA: select a browser page, capture a click, inspect the request and follow the export script." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Reverse Engineering Guides — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Learn REA through short worked examples: a native calculation, an Electron CSV export and a browser request." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="JavaScript and Electron Analysis — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Trace a Notes CSV export through a renderer API, preload and IPC handler with REA. Includes downloadable example files and a verified analysis result." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Native Binary Analysis — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Recover a native calculation with REA: inspect instructions, follow a caller, read constants and check reconstructed C." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="REA — Reverse Engineering for Your Coding Agent" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Reverse engineer apps, binaries and browser behavior with your coding agent. Follow clear guides and try interactive examples with REA." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Aegis APK Reverse Engineering: Login Codes — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Inspect the Aegis Android APK with REA, recover its six-digit login-code calculation and try a reconstruction with an adjustable clock." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="CTF Reverse Engineering: DownUnderCTF Flag Checker — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Use REA to solve DownUnderCTF's masked squares flag checker. Find the checking functions, extract the masks and compare a recovered flag with the original program." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="DX-Ball Reverse Engineering: Sound Panning — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Follow a DX-Ball reconstruction from binary analysis through REA to maintained C, original-x86 tests and matching compiled function bytes." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Reverse Engineering Case Studies — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Follow REA investigations through code, figures and demos: an Android authenticator, DX-Ball, Notion, TH04 and a DownUnderCTF flag checker." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Notion Electron Reverse Engineering: Clipboard — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format." />
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="en_US" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="TH04 Reverse Engineering: DOS Bullet Patterns — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Inspect TH04's original 16-bit DOS code with REA. Follow the assembly and recovered C++ to see how a ring of bullets is spaced and aimed at the player." />
|
||||
|
||||
@@ -3,10 +3,10 @@
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
<a href="https://github.com/morluto/rea">$t_source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">$t_license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">$t_community</a
|
||||
><a href="https://x.com/reatools">$t_followUs</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
@@ -15,11 +15,11 @@
|
||||
id="copy-status"
|
||||
role="status"
|
||||
aria-live="polite"
|
||||
data-copied="Copied"
|
||||
data-selected="Selected"
|
||||
data-status-copied="Code copied to clipboard."
|
||||
data-status-selected="Code selected. Use your keyboard to copy it."
|
||||
data-copied="$t_copied"
|
||||
data-selected="$t_selected"
|
||||
data-status-copied="$t_statusCopied"
|
||||
data-status-selected="$t_statusSelected"
|
||||
></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
<a class="back-to-top" href="#top" aria-label="$t_backToTop">
|
||||
<span aria-hidden="true">↑</span> $t_top
|
||||
</a>
|
||||
|
||||
@@ -1,21 +1,19 @@
|
||||
<!-- prettier-ignore -->
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<a class="skip-link" href="#main">$t_skipLink</a>
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="$base" aria-label="REA home"
|
||||
<a class="brand" href="$brand" aria-label="$t_home"
|
||||
><span class="brand-name">REA</span
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">$navigation</nav>
|
||||
<div class="header-social">
|
||||
<nav class="navigation" aria-label="$t_mainNavigation">$navigation</nav>
|
||||
<div class="header-social">$language_menu
|
||||
<a
|
||||
class="nav-github"
|
||||
href="https://github.com/morluto/rea"
|
||||
aria-label="REA on GitHub"
|
||||
title="REA on GitHub"
|
||||
data-label-one="REA on GitHub ({count} star)"
|
||||
data-label-other="REA on GitHub ({count} stars)"
|
||||
aria-label="$t_github"
|
||||
title="$t_github"$github_star_labels
|
||||
>
|
||||
<svg
|
||||
width="22"
|
||||
@@ -34,8 +32,8 @@
|
||||
<a
|
||||
class="nav-discord"
|
||||
href="https://discord.gg/GkcryMnJDM"
|
||||
aria-label="Join REA on Discord"
|
||||
title="Join REA on Discord"
|
||||
aria-label="$t_discord"
|
||||
title="$t_discord"
|
||||
>
|
||||
<svg
|
||||
width="22"
|
||||
@@ -53,8 +51,8 @@
|
||||
<a
|
||||
class="nav-x"
|
||||
href="https://x.com/reatools"
|
||||
aria-label="Follow REA on X"
|
||||
title="Follow REA on X"
|
||||
aria-label="$t_followRea"
|
||||
title="$t_followRea"
|
||||
>
|
||||
<svg
|
||||
width="18"
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="$canonical" />
|
||||
<link rel="canonical" href="$canonical" />$hreflang
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:locale" content="$og_locale" />$og_locale_alternates
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="$title" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="$description" />
|
||||
@@ -21,7 +23,7 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
content="$t_imageAlt"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
@@ -34,5 +36,5 @@
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
content="$t_imageAlt"
|
||||
/>
|
||||
|
||||
@@ -0,0 +1,230 @@
|
||||
# Translating the website
|
||||
|
||||
The home page, Get started, the Guides index and the FAQ are translated into six
|
||||
languages. Guide pages, the blog, showcases and examples remain in English;
|
||||
translated pages link to their English versions.
|
||||
|
||||
| Directory | `lang` and `hreflang` | `og:locale` | Menu name |
|
||||
| ----------- | --------------------- | ----------- | --------- |
|
||||
| (site root) | `en` | `en_US` | English |
|
||||
| `zh-hans/` | `zh-Hans` | `zh_CN` | 简体中文 |
|
||||
| `zh-hant/` | `zh-Hant` | `zh_TW` | 繁體中文 |
|
||||
| `ja/` | `ja` | `ja_JP` | 日本語 |
|
||||
| `ko/` | `ko` | `ko_KR` | 한국어 |
|
||||
| `de/` | `de` | `de_DE` | Deutsch |
|
||||
| `fr/` | `fr` | `fr_FR` | Français |
|
||||
|
||||
`LANGUAGES` in `scripts/website.py` owns these values. Each language's shared
|
||||
UI text (navigation, header and footer labels, copy messages, the stale-page
|
||||
notice and the sharing-image description) lives in `locales/<language>.json`.
|
||||
The site never redirects by browser language.
|
||||
|
||||
## How a translated page works
|
||||
|
||||
A translation is an ordinary HTML file at the English page's path under its
|
||||
language directory, such as `public/zh-hant/get-started/index.html`. Its head
|
||||
records where it came from:
|
||||
|
||||
```html
|
||||
<!-- website:translation source-sha256="…" status="draft" -->
|
||||
```
|
||||
|
||||
- `source-sha256` identifies the English text the translation was made from.
|
||||
It hashes the English page without its shared regions and copied code
|
||||
blocks, so template and command changes do not count.
|
||||
- `status="draft"` pages carry `noindex`. They are left out of the sitemap,
|
||||
hreflang, the language menu and other pages' navigation; open them by URL.
|
||||
- `status="reviewed" reviewed="YYYY-MM-DD"` pages are indexable and linked.
|
||||
Only a native-speaking reviewer marks a page reviewed.
|
||||
|
||||
`python3 scripts/website.py sync` maintains everything shared:
|
||||
|
||||
- The header, footer and sharing regions use the page's locale. The language
|
||||
menu offers the same page in each reviewed language, or that language's
|
||||
reviewed home page, and leaves out languages with neither.
|
||||
- Navigation points to reviewed pages in the same language. Links to English
|
||||
pages, such as Showcases and Blog, carry a small `EN` badge.
|
||||
- Reviewed versions of a page list each other with `hreflang` alternates and
|
||||
`x-default` pointing to English.
|
||||
- Every code block that a Copy button targets is copied from the English page
|
||||
by ID. Translations never hold their own copy of a command; edit the English
|
||||
page and run `sync`.
|
||||
- When the English text changes, the `website:translation-notice` region at
|
||||
the top of the content says the page may be out of date and links to the
|
||||
English version. Updating the hash removes it.
|
||||
|
||||
## Create and update a translation
|
||||
|
||||
1. Create the draft from the English page:
|
||||
|
||||
```sh
|
||||
python3 scripts/website.py translate zh-hant get-started
|
||||
python3 scripts/website.py translate ja / # the home page
|
||||
```
|
||||
|
||||
The command sets `lang`, adds the record and `noindex`, rewrites relative
|
||||
links for the new directory, links pages that already exist in that
|
||||
language and runs `sync`.
|
||||
|
||||
2. Translate the text in place, following the rules below. Keep the page's
|
||||
structure: element IDs, Copy buttons and `data-msg-*` attributes stay as in
|
||||
English.
|
||||
3. Run `python3 scripts/website.py check` and `npm run format:check`.
|
||||
4. Run `python3 scripts/website.py translations` to see each page's status,
|
||||
whether its English source changed, the OS names still to confirm and any
|
||||
UI strings still in English.
|
||||
|
||||
When the English page changes, `check` warns, and after `sync` the notice
|
||||
appears. Update the translation's text first. Then set `source-sha256` to the
|
||||
value `translations` prints. Never refresh the hash without updating the
|
||||
content: the hash is the record that the translation matches that English text.
|
||||
|
||||
### What the checks enforce
|
||||
|
||||
Failures:
|
||||
|
||||
- A missing or invalid record, a draft without `noindex`, or a reviewed page
|
||||
with `noindex` or without its review date.
|
||||
- A copied code block that differs from English (run `sync`).
|
||||
- While the record matches the English page: different element IDs, Copy
|
||||
buttons or `data-msg-*` attributes.
|
||||
- In Japanese and Chinese, whitespace between two CJK characters. A line break
|
||||
inside a sentence renders as a visible gap, so keep CJK text unwrapped and
|
||||
let the formatter break lines at existing spaces.
|
||||
|
||||
Warnings:
|
||||
|
||||
- The English source changed since the translation, or the notice needs `sync`.
|
||||
- Inline code in prose differs from English.
|
||||
- A link points to an English page that has a reviewed translation.
|
||||
- A locale still has English placeholders. List intentionally identical
|
||||
strings in that locale's `sameAsEnglish`.
|
||||
|
||||
## Translation rules
|
||||
|
||||
- Keep in English: REA, MCP, CLI, Node.js, npm, Ghidra, Hopper, IDA, JDK,
|
||||
product and client names (Claude Code, Codex, OpenCode, Cursor, Gemini CLI,
|
||||
Windsurf, Grok Build, VS Code), and every command, path, code sample, flag,
|
||||
environment variable and file name. Keep the brand line "Reverse Engineer
|
||||
Anything" in English.
|
||||
- Translate the prompts readers paste into their coding agent. Keep any
|
||||
command or path inside a prompt unchanged, and check that the translated
|
||||
prompt still asks for the same actions.
|
||||
- Use the OS menu and button names that the OS shows in that language. Mark
|
||||
each one for review with `data-os-ui="windows"`, `"macos"` or `"linux"`, for
|
||||
example `<em data-os-ui="windows">複製路徑</em>`. Windows 10 and 11 sometimes
|
||||
differ; name both when they do.
|
||||
- When an OS shows an error message in the reader's language, give the
|
||||
translated message and the English original, since many readers use an
|
||||
English system.
|
||||
- Follow the glossary. It comes from the README translations in the
|
||||
repository root, with the zh-Hant changes noted below.
|
||||
- Leave a space between CJK text and Latin words or numbers, as the READMEs
|
||||
do: `使用 REA 的 MCP 服務`. In French, put a non-breaking space (U+00A0)
|
||||
before `:` and inside `« »`, and a narrow non-breaking space (U+202F) before
|
||||
`?`, `!` and `;`.
|
||||
- Keep `<title>` and the meta description natural for search in that
|
||||
language. They must not repeat another page's title.
|
||||
|
||||
### Register
|
||||
|
||||
| Language | Prose | Agent prompts |
|
||||
| -------- | ---------------- | -------------------------- |
|
||||
| zh-Hans | 你 | 你; direct requests |
|
||||
| zh-Hant | 你 | 你; direct requests |
|
||||
| ja | です・ます | 〜してください |
|
||||
| ko | 해요체 (`-세요`) | 반말 (`-해 줘`), as README |
|
||||
| de | du | du |
|
||||
| fr | vous | tu, as in the README |
|
||||
|
||||
### Glossary
|
||||
|
||||
Terms marked † do not appear in the README translations and are proposals for
|
||||
review. zh-Hant uses Taiwan-standard terms; where `README_zh-TW.md` differs,
|
||||
this table wins and the README will be aligned separately.
|
||||
|
||||
| English | zh-Hans | zh-Hant | ja | ko | fr | de |
|
||||
| -------------------------- | ---------------------- | --------------------------- | ---------------------------------------- | ------------------------- | ---------------------------- | -------------------------------- |
|
||||
| reverse engineering | 逆向工程 | 逆向工程 | リバースエンジニアリング | 리버스 엔지니어링 | rétro-ingénierie | Reverse Engineering |
|
||||
| (coding) agent | 智能体 (编程智能体†) | AI 代理 (程式設計 AI 代理†) | エージェント (コーディングエージェント†) | 에이전트 (코딩 에이전트†) | agent (agent de code†) | Agent (Coding-Agent†) |
|
||||
| setup / set up | 设置 / 设置流程 | 設定 / 設定流程 | セットアップ | 설정 / 설정 과정 | configurer; « Setup » | Einrichtung / einrichten |
|
||||
| approve | 批准 | 核准 | 承認 | 승인 | approuver | bestätigen |
|
||||
| restart | 重启 | 重新啟動 | 再起動 | 다시 시작 | redémarrer | neu starten |
|
||||
| MCP server | MCP 服务 | MCP 服務 | MCP サーバー | MCP 서버 | serveur MCP | MCP-Server |
|
||||
| client | 客户端 | 用戶端 | クライアント | 클라이언트 | client | Client† |
|
||||
| skill | skill | skill | スキル | 스킬 | le skill | der Skill |
|
||||
| provider | 提供方 | 提供者 | プロバイダー | 제공자 | fournisseur | Provider |
|
||||
| native analysis | 原生分析 | 原生分析 | ネイティブ分析 | 네이티브 분석 | analyse native | native Analyse |
|
||||
| analysis engine | 分析引擎 | 分析引擎 | 分析エンジン | 분석 엔진 | moteur d'analyse | Analyse-Engine |
|
||||
| binary | 二进制文件 | 二進位檔案 | バイナリ | 바이너리 | binaire | Binärdatei |
|
||||
| executable† | 可执行文件 | 執行檔 | 実行ファイル | 실행 파일 | exécutable | ausführbare Datei |
|
||||
| library† | 库 | 函式庫 | ライブラリ | 라이브러리 | bibliothèque | Bibliothek |
|
||||
| function | 函数 | 函式 | 関数 | 함수 | fonction† | Funktion† |
|
||||
| pseudocode | 伪代码 | 偽程式碼 | 疑似コード | 의사 코드 | pseudo-code | Pseudocode |
|
||||
| assembly | 汇编 | 組合語言 | アセンブリ | 어셈블리 | assembleur | Assemblercode |
|
||||
| decompile | 反编译 | 反編譯 | 逆コンパイル | 디컴파일 | décompiler† | dekompilieren† |
|
||||
| code | 代码 | 程式碼 | コード | 코드 | code | Code |
|
||||
| implement / implementation | 实现 | 實作 | 実装 | 구현 | implémenter / implémentation | implementieren / Implementierung |
|
||||
| via / through | 通过 | 透過 | 経由で | 통해 | via | über |
|
||||
| evidence | 证据 | 證據 | 根拠 | 근거 | preuves | Belege |
|
||||
| Evidence (product record) | Evidence | Evidence | Evidence | Evidence | Evidence | Evidence |
|
||||
| findings | 发现 | 發現 | 調査結果 | 조사 결과 | constatations | Ergebnisse |
|
||||
| target | 目标 | 目標 | 対象 | 대상 | cible | Ziel |
|
||||
| investigation | 调查 | 調查 | 調査 | 조사 | investigation | Untersuchung |
|
||||
| terminal | 终端 | 終端機 | ターミナル | 터미널 | terminal | Terminal |
|
||||
| module / import | 模块 / 导入 | 模組 / 匯入 | モジュール / インポート | 모듈 / 임포트 | modules / imports | Module / Imports |
|
||||
| session | 会话 | 工作階段 | セッション | 세션 | session† | Sitzung† |
|
||||
| configuration | 配置 | 設定 | 設定 | 설정 | configuration | Konfiguration |
|
||||
| backup | 备份 | 備份 | バックアップ | 백업 | sauvegarde | Sicherung / sichern |
|
||||
| update | 更新 | 更新 | 更新 | 업데이트 / 갱신 | mettre à jour | aktualisieren |
|
||||
| headless | 无界面 | 無介面 | ヘッドレス | 헤드리스 | headless† | headless† |
|
||||
| locally | 本机 | 本機 | ローカル | 로컬 | localement | lokal |
|
||||
| bug / issue | 错误 / issue | 錯誤 / issue | バグ / issue | 버그 / issue | bug / issue | Fehler / Issue |
|
||||
| community | 社区 | 社群 | コミュニティ† | 커뮤니티 | communauté† | Community† |
|
||||
| Showcases | 案例 | 案例 | 事例 | 사례 | Études de cas | Fallstudien |
|
||||
| Guides | 指南 | 指南 | ガイド | 가이드 | Guides | Anleitungen |
|
||||
| FAQ | 常见问题 | 常見問題 | よくある質問 | 자주 묻는 질문 | Questions fréquentes | Häufige Fragen |
|
||||
| Get started | 快速开始 | 快速開始 | クイックスタート | 빠른 시작 | Démarrage rapide | Schnellstart |
|
||||
| Blog† | 博客 | 部落格 | ブログ | 블로그 | Blog | Blog |
|
||||
| Copy / Copied / Selected† | 复制 / 已复制 / 已选中 | 複製 / 已複製 / 已選取 | コピー / コピーしました / 選択しました | 복사 / 복사됨 / 선택됨 | Copier / Copié / Sélectionné | Kopieren / Kopiert / Markiert |
|
||||
| Skip to content† | 跳到正文 | 跳至主要內容 | 本文へスキップ | 본문으로 건너뛰기 | Aller au contenu | Zum Inhalt springen |
|
||||
| Back to top† | 返回顶部 | 回到頂端 | ページの先頭へ | 맨 위로 | Retour en haut | Nach oben |
|
||||
|
||||
### OS names to confirm
|
||||
|
||||
These are starting points, not confirmed names. Mark each use with
|
||||
`data-os-ui` and have the reviewer confirm it on that OS in that language.
|
||||
|
||||
| English | zh-Hans | zh-Hant | ja | ko | fr | de |
|
||||
| -------------------------------------------- | ---------------------------- | ---------------------------- | ---------------------- | ---------------------------- | -------------------------------------- | ------------------------- |
|
||||
| File Explorer (Windows) | 文件资源管理器 | 檔案總管 | エクスプローラー | 파일 탐색기 | Explorateur de fichiers | Explorer |
|
||||
| Copy as path (Windows 10 / 11) | 复制为路径 / 复制文件地址 | 複製為路徑 / 複製路徑 | パスのコピー | 경로로 복사 | Copier en tant que chemin d'accès | Als Pfad kopieren |
|
||||
| Start menu (Windows) | 开始菜单 | 開始功能表 | スタートメニュー | 시작 메뉴 | menu Démarrer | Startmenü |
|
||||
| "running scripts is disabled on this system" | translated message + English | translated message + English | translated + English | translated + English | translated + English | translated + English |
|
||||
| Finder (macOS) | 访达 | Finder | Finder | Finder | Finder | Finder |
|
||||
| Copy "…" as Pathname (macOS) | 将"…"拷贝为路径名称 | 將「…」拷貝為路徑名稱 | "…"のパス名をコピー | "…"을(를) 경로 이름으로 복사 | Copier « … » en tant que nom de chemin | „…" als Pfadname kopieren |
|
||||
| Show Package Contents (macOS) | 显示包内容 | 顯示套件內容 | パッケージの内容を表示 | 패키지 내용 보기 | Afficher le contenu du paquet | Paketinhalt zeigen |
|
||||
| Terminal (macOS app) | 终端 | 終端機 | ターミナル | 터미널 | Terminal | Terminal |
|
||||
|
||||
## Review checklist
|
||||
|
||||
A reviewer reads the translation beside the English page and checks:
|
||||
|
||||
- The meaning matches, with nothing added or dropped, and the glossary and
|
||||
register are followed.
|
||||
- Commands, paths, flags and product names are unchanged. Copied code blocks
|
||||
come from English automatically.
|
||||
- Each translated agent prompt, pasted into a real coding agent, leads to the
|
||||
same actions as the English prompt (for the setup prompt: it runs
|
||||
`npx rea-agents@latest setup` and shows the plan before changing anything).
|
||||
- Every `data-os-ui` name matches the OS in that language. `translations`
|
||||
lists them.
|
||||
- The title and description read naturally in search results.
|
||||
- The page works at 320, 375, 768, 1024 and 1440 pixels wide: headings, the
|
||||
header and language menu, Copy buttons and their announced status, opened
|
||||
details, and the back-to-top link.
|
||||
|
||||
To mark the page reviewed, change its record to
|
||||
`status="reviewed" reviewed="YYYY-MM-DD"`, remove its `noindex` line and run
|
||||
`sync`, which adds it to the language menu, hreflang and other pages'
|
||||
navigation. Commit those regenerated pages with it.
|
||||
Reference in New Issue
Block a user