6.9 KiB
Website translations
A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
— N0zoM1z0
The same standard applies in every language. A translation should help someone understand the example and try it. Clear, accurate wording matters more than a literal imitation of English sentences.
Edit a translation
Use the Python environment in the website README. Pick a language
from languages.json, then edit its messages.po in a text editor, Poedit or
another gettext editor. Each entry includes its source page and line:
#: website/public/faq/index.html:200
msgctxt "page:faq/index.html"
msgid "How do I install REA?"
msgstr "如何安装 REA？"
Change msgstr. Keep msgid and msgctxt. Add reviewer notes with # comments
when useful. Shared navigation uses the shared context; page-specific wording
has its own context. The same English sentence may need different wording in a
different case study.
python3 scripts/website.py translations status --language zh-CN
python3 scripts/website.py translations check --language zh-CN
python3 scripts/website.py serve
Open http://127.0.0.1:4173/zh-CN/. The language selector opens the equivalent
page in another edition. Check the page you edited, its figures and its copy
buttons. Rebuild a running preview with python3 scripts/prepare-website.py.
Before submitting a change, run python3 scripts/website.py check.
Use translations check --strict to require every message to be translated.
Keep complete sentences and protected evidence
Paragraphs remain complete translation units. Inline emphasis, links, code and literal commands use named placeholders:
#. {ph0}: <a href="guides/">
#. {ph1}: </a>
msgctxt "page:index.html"
msgid "Already know RE? {ph0}Skip to analysis guides →{ph1}"
msgstr "已经了解逆向工程？{ph0}直接看分析指南 →{ph1}"
Move a linked or emphasized phrase when your language needs a different sentence
order. Keep its opening and closing placeholders around that phrase. Preserve
each placeholder exactly once per occurrence. Checks reject missing placeholders
and broken tag nesting. Interaction messages use names such as {speed} and
{seconds}; keep those names too.
Code blocks, inline code and translate="no" spans are copied from the source.
Commands, filenames, paths, URLs, hashes and observed values must retain their
meaning. Never translate npx rea-agents@latest setup into prose. Preserve product
names such as REA, Codex, Claude Code, Ghidra and Homebrew. Explain technical terms
in the surrounding text when needed.
In these articles, an agent is the reader's AI coding assistant. A call is a function call; a library is a software library. A port means adapting a program to another platform. An oracle is a concrete reference or checker used to verify a reconstruction. Translate those meanings rather than unrelated dictionary senses. Distinguish native machine-code analysis from local analysis, and .NET assemblies from assembly instructions. Android names the operating system; C names the programming language. Read the whole sentence when a dictionary sense would change what the software does.
Review the question, REA's findings, the agent's reasoning and the verification result together. Keep recorded versions, milestone counts, unknowns and source attribution accurate. Blog essays can use a personal voice. Translated quotes should be identifiable as translations and retain a link to the original.
Update the English source
python3 scripts/website.py sync
python3 scripts/website.py translations extract
python3 scripts/website.py translations status
python3 scripts/website.py check
Extraction generates messages.pot and merges it into each PO catalog. Unchanged
sentences keep their translations and reviewer comments. Changed sentences start
empty; removed entries are retained as obsolete translation memory. Nothing
silently accepts a guessed match. An editor's fuzzy entry remains pending until
someone reviews it and removes the flag.
If a page needs a missing or fuzzy message, its language route temporarily shows
the complete English page with a visible notice. It has noindex and stays out
of the sitemap and translated hreflang alternatives. Links from ready pages
lead to ready editions or the English source. Completing the required entries
restores the translated page and its search metadata at the next build. Runtime
messages affect only pages that use their script; an untranslated dinosaur status
does not turn the FAQ into an English fallback.
public/ remains the authored English site. _site/ is disposable generated
output. The sitemap discovers every ready edition automatically. Pages and
Cloudflare publish this same artifact. No translation API runs during a build
or in a reader's browser.
Figure labels and accessibility descriptions are included in the catalogs under
figure:<filename>. Keep labels short enough for the diagram. Interaction text
is extracted directly from t("message") calls in public/assets/*.js, with
source locations in the catalog. Keep named values instead of concatenating
translated fragments.
Language coverage and initial translations
languages.json lists the same editions as the English root README and the translations in docs/readme/, with native names,
standard language tags and text direction. English keeps its existing routes;
other editions use a language prefix such as /ja/ or /pt-BR/. Arabic and
Persian use right-to-left page layouts; code and numeric demos remain left to
right. The two Notes target applications and the downloadable source archive
remain the original investigation inputs.
Greek (el) has a translated README and a partially translated website catalog.
Incomplete website pages use the labeled English fallback until their required
messages are translated and reviewed.
The first catalogs started with machine-assisted drafts. They include editorial corrections to navigation, prompts and technical terminology. Traditional Chinese started from the Simplified Chinese draft and is maintained independently. Further language review and more natural phrasing are welcome. Submit the PO changes with the page and language you checked; a screenshot can help explain a layout issue.
Why gettext
PO catalogs have source references, reviewer comments and explicit pending translations. They can be edited locally and can later be connected to Weblate without replacing the site's translation format. This keeps one authored layout and a small offline build instead of maintaining separate HTML trees.
See GNU gettext's PO format, Weblate's translation workflows and Google's localized-page guidance.