diff --git a/.github/workflows/website-pages.yml b/.github/workflows/website-pages.yml index 22a37281a..27d127a88 100644 --- a/.github/workflows/website-pages.yml +++ b/.github/workflows/website-pages.yml @@ -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' diff --git a/scripts/test-website.py b/scripts/test-website.py index 8f555b62d..9cedd6a09 100644 --- a/scripts/test-website.py +++ b/scripts/test-website.py @@ -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 & "result"', 'Check "quotes" & .') @@ -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"(.*?)", r"\1 (zh-Hant)", path.read_text(), count=1) + source = source.replace('status="draft"', 'status="reviewed" reviewed="2026-10-11"', 1) + path.write_text(source.replace(' \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('', source) + self.assertIn('', source) + self.assertEqual( + WEBSITE.translation_record(source), + {"source-sha256": WEBSITE.source_digest(english), "status": "draft"}, + ) + self.assertIn('href="../../assets/styles.css"', source) + self.assertIn('', source) + self.assertIn('href="../../guides/javascript/"', source) + self.assertIn('Get started', source + ) + self.assertIn( + 'ShowcasesEN', + source, + ) + self.assertIn('
  • English
  • ', source) + self.assertIn('', 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'', english) + self.assertIn('', english) + self.assertIn( + '
  • 繁體中文
  • ', english + ) + self.assertNotIn("language-menu", (site / "faq/index.html").read_text()) + translated = (site / "zh-hant/get-started/index.html").read_text() + self.assertIn('', 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( + '
  • 繁體中文
  • ', + (site / "faq/index.html").read_text(), + ) + translated = (site / "zh-hant/get-started/index.html").read_text() + self.assertIn('", 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", page.read_text()) + self.assertNotIn("translation-notice\"", page.read_text()) + self.assertEqual(translation_errors(root)[0], []) + + text = "

    Restart your client when setup finishes.

    " + changed = english_path.read_text().replace(text, "

    Restart your client after setup.

    ", 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( + '

    The English page has changed since this translation. ' + 'Read the English version.

    ', + 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("

    Restart your client after setup.

    ", 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", "rea-agents@1", 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 = ( + ("

    Restart your client when setup finishes.

    ", "

    完成後\n 重新啟動。

    ", "renders as a gap"), + ('id="install-node"', 'id="node"', "element IDs differ"), + ('data-copy="install-cli"', 'data-copy="node-check"', "copy buttons differ"), + (' \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("

    Restart your client when setup finishes.

    ", "

    重新啟動 REA 用戶端。

    ", 1)) + self.assertEqual(translation_errors(root)[0], []) + page.write_text(original.replace("node -v", "node -V", 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() diff --git a/scripts/verify-website.py b/scripts/verify-website.py index 889d77394..cb59896f7 100644 --- a/scripts/verify-website.py +++ b/scripts/verify-website.py @@ -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 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 ") + 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 diff --git a/scripts/website.py b/scripts/website.py index fd636897a..6a0500516 100644 --- a/scripts/website.py +++ b/scripts/website.py @@ -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/.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"") +SHARED_REGION = re.compile(r".*?", re.S) +NOTICE_START = " \n" +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'(]*\bid="{re.escape(identifier)}"[^>]*>)(.*?)()', 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 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' {label}') + badge = "" + if target_language != language: + attributes += ' hreflang="en"' + badge = 'EN' + links.append(f' {escape(strings[key])}{badge}') + + 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'
  • {details.name}
  • ' + ) + language_menu = "" + if len(entries) > 1: + language_menu = "\n".join(( + "", + '
    ', + " ", + ' ", + f' {escape(strings["language"])}: ' + f'{LANGUAGES[language].name}', + " ", + '
      ', + *entries, + "
    ", + "
    ", + )) + + 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\n' + for code in members: + if code != language: + locale_alternates += ( + f'\n\n' + ) + + 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'' + f'{escape(strings["staleNoticeLink"])}' + ) + message = escape(strings["staleNotice"]).replace("{link}", link) + return f' \n

    {message}

    \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" \n" - end = f" " - 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" \n", f" ", 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('') != 1 or source.count(" \n") != 1: + raise ValueError(f"{english}: needs and one sharing region") + main = re.search(r"^ {4}]*>\n", source, re.M) + if main is None: + raise ValueError(f"{english}: needs a
    element on its own line") + source = source.replace('', f'') + source = relocate_references(source, english, language, state) + record = ( + f' \n' + ) + robots = "" if '\n' + source = source.replace(" \n", robots + record + " \n") + main = re.search(r"^ {4}]*>\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="([^"]+)"[^>]*>(.*?) > — 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 `` 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 diff --git a/website/locales/de.json b/website/locales/de.json new file mode 100644 index 000000000..4740da475 --- /dev/null +++ b/website/locales/de.json @@ -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": [] +} diff --git a/website/locales/en.json b/website/locales/en.json new file mode 100644 index 000000000..4740da475 --- /dev/null +++ b/website/locales/en.json @@ -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": [] +} diff --git a/website/locales/fr.json b/website/locales/fr.json new file mode 100644 index 000000000..4740da475 --- /dev/null +++ b/website/locales/fr.json @@ -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": [] +} diff --git a/website/locales/ja.json b/website/locales/ja.json new file mode 100644 index 000000000..3aa23100e --- /dev/null +++ b/website/locales/ja.json @@ -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": [] +} diff --git a/website/locales/ko.json b/website/locales/ko.json new file mode 100644 index 000000000..3aa23100e --- /dev/null +++ b/website/locales/ko.json @@ -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": [] +} diff --git a/website/locales/zh-hans.json b/website/locales/zh-hans.json new file mode 100644 index 000000000..3aa23100e --- /dev/null +++ b/website/locales/zh-hans.json @@ -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": [] +} diff --git a/website/locales/zh-hant.json b/website/locales/zh-hant.json new file mode 100644 index 000000000..3aa23100e --- /dev/null +++ b/website/locales/zh-hant.json @@ -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": [] +} diff --git a/website/public/assets/styles.css b/website/public/assets/styles.css index 60fdfb6c5..cd03ad3a4 100644 --- a/website/public/assets/styles.css +++ b/website/public/assets/styles.css @@ -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); + } +} diff --git a/website/public/blog/index.html b/website/public/blog/index.html index b0ad8f862..70075dfb5 100644 --- a/website/public/blog/index.html +++ b/website/public/blog/index.html @@ -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." /> diff --git a/website/public/blog/touhou-reconstruction/index.html b/website/public/blog/touhou-reconstruction/index.html index 38fa15868..33a5e2b31 100644 --- a/website/public/blog/touhou-reconstruction/index.html +++ b/website/public/blog/touhou-reconstruction/index.html @@ -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." /> diff --git a/website/public/examples/dino-lab/index.html b/website/public/examples/dino-lab/index.html index b2bb4d227..622c00e13 100644 --- a/website/public/examples/dino-lab/index.html +++ b/website/public/examples/dino-lab/index.html @@ -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." /> diff --git a/website/public/faq/index.html b/website/public/faq/index.html index d49992cfa..3e331da37 100644 --- a/website/public/faq/index.html +++ b/website/public/faq/index.html @@ -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." /> diff --git a/website/public/first-investigation/index.html b/website/public/first-investigation/index.html index d42217dc4..8fbf8f8ba 100644 --- a/website/public/first-investigation/index.html +++ b/website/public/first-investigation/index.html @@ -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." /> diff --git a/website/public/get-started/index.html b/website/public/get-started/index.html index ec6edbdd5..37ffca548 100644 --- a/website/public/get-started/index.html +++ b/website/public/get-started/index.html @@ -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." /> diff --git a/website/public/guides/browser/index.html b/website/public/guides/browser/index.html index cc6598e65..ce43a56d5 100644 --- a/website/public/guides/browser/index.html +++ b/website/public/guides/browser/index.html @@ -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." /> diff --git a/website/public/guides/index.html b/website/public/guides/index.html index c16817918..7b309891c 100644 --- a/website/public/guides/index.html +++ b/website/public/guides/index.html @@ -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." /> diff --git a/website/public/guides/javascript/index.html b/website/public/guides/javascript/index.html index 1b66a532f..00dc700f4 100644 --- a/website/public/guides/javascript/index.html +++ b/website/public/guides/javascript/index.html @@ -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." /> diff --git a/website/public/guides/native/index.html b/website/public/guides/native/index.html index b0ec8c01b..ea60bf91a 100644 --- a/website/public/guides/native/index.html +++ b/website/public/guides/native/index.html @@ -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." /> diff --git a/website/public/index.html b/website/public/index.html index fde1db3dc..bed02e04b 100644 --- a/website/public/index.html +++ b/website/public/index.html @@ -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." /> diff --git a/website/public/showcase/aegis/index.html b/website/public/showcase/aegis/index.html index db569322e..f16f4b896 100644 --- a/website/public/showcase/aegis/index.html +++ b/website/public/showcase/aegis/index.html @@ -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." /> diff --git a/website/public/showcase/ctf/index.html b/website/public/showcase/ctf/index.html index 8eebc5272..3c10bb2c3 100644 --- a/website/public/showcase/ctf/index.html +++ b/website/public/showcase/ctf/index.html @@ -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." /> diff --git a/website/public/showcase/dx-ball/index.html b/website/public/showcase/dx-ball/index.html index 893666e2e..9192e41e1 100644 --- a/website/public/showcase/dx-ball/index.html +++ b/website/public/showcase/dx-ball/index.html @@ -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." /> diff --git a/website/public/showcase/index.html b/website/public/showcase/index.html index f98160d95..ddcf8aeb2 100644 --- a/website/public/showcase/index.html +++ b/website/public/showcase/index.html @@ -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." /> diff --git a/website/public/showcase/notion/index.html b/website/public/showcase/notion/index.html index 05d99e2a4..e096e8ae6 100644 --- a/website/public/showcase/notion/index.html +++ b/website/public/showcase/notion/index.html @@ -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." /> diff --git a/website/public/showcase/th04/index.html b/website/public/showcase/th04/index.html index 2bf16694d..955f5ef20 100644 --- a/website/public/showcase/th04/index.html +++ b/website/public/showcase/th04/index.html @@ -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." /> diff --git a/website/templates/footer.html.tmpl b/website/templates/footer.html.tmpl index 63c71930a..8431ddb78 100644 --- a/website/templates/footer.html.tmpl +++ b/website/templates/footer.html.tmpl @@ -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> diff --git a/website/templates/header.html.tmpl b/website/templates/header.html.tmpl index 9a169f15d..d9069befe 100644 --- a/website/templates/header.html.tmpl +++ b/website/templates/header.html.tmpl @@ -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" diff --git a/website/templates/sharing.html.tmpl b/website/templates/sharing.html.tmpl index 218eb9b5e..39e13fa2c 100644 --- a/website/templates/sharing.html.tmpl +++ b/website/templates/sharing.html.tmpl @@ -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" /> diff --git a/website/translation.md b/website/translation.md new file mode 100644 index 000000000..6db0f0d35 --- /dev/null +++ b/website/translation.md @@ -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.