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:
Kaoru0822
2026-10-11 07:23:29 +00:00
co-authored by Claude Opus 5.5
parent 80f6365523
commit ce58aebc0e
35 changed files with 1564 additions and 71 deletions
+3
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
+34
View File
@@ -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": []
}
+34
View File
@@ -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": []
}
+34
View File
@@ -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": []
}
+33
View File
@@ -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": []
}
+33
View File
@@ -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": []
}
+33
View File
@@ -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": []
}
+33
View File
@@ -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": []
}
+178 -3
View File
@@ -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);
}
}
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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." />
+2
View File
@@ -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&#x27;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." />
+2
View File
@@ -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&#x27;s clipboard API through Electron&#x27;s preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format." />
+2
View File
@@ -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&#x27;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." />
+10 -10
View File
@@ -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>
+10 -12
View File
@@ -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"
+5 -3
View File
@@ -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"
/>
+230
View File
@@ -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.