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>
52 lines
3.2 KiB
Markdown
52 lines
3.2 KiB
Markdown
# Website maintenance
|
|
|
|
> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
|
|
>
|
|
> — N0zoM1z0
|
|
|
|
Read [README.md](README.md) and [style-guide.md](style-guide.md) before changing
|
|
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. 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/` 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
|
|
`new-page` for a reading-page scaffold, then add its index link. Keep a draft's
|
|
visible label and `noindex` until the content is ready.
|
|
- Show what REA returns and how the agent uses it. Preserve source attribution,
|
|
target identity and verification scope.
|
|
- Blog articles teach methods, decisions and workflows through concrete cases.
|
|
Lead with the takeaway. Essays can develop a personal argument through
|
|
experience; figures are optional and should add an explanation the prose
|
|
needs. Use engine details only when they explain a decision. Label working
|
|
outlines and mark them `noindex`.
|
|
- Keep personal paths, account data, credentials and raw captures outside the
|
|
public assets. Use generic inputs and label shortened display paths.
|
|
- Follow the same clear writing standard in search titles and descriptions.
|
|
Give each content page its own absolute `https://rea.tools/` canonical and
|
|
matching sharing metadata; keep navigation relative. The sitemap is generated
|
|
from HTML automatically. Mark example applications `noindex` in the head and
|
|
keep them crawlable. Maintain the SVG sharing source, not the generated PNG.
|
|
- Check both local root and `/rea/` paths, mobile layouts, expanded details,
|
|
copying and downloads. Run `python3 scripts/website.py check`, using the Python
|
|
environment described in the README. It rejects drift rather than silently
|
|
rewriting shared HTML. Use `website.py links` for an optional network audit;
|
|
distinguish missing targets from access denials and unverified fragments.
|
|
- Check setup and support statements against the current installation/provider
|
|
guides and released package. Preserve historical case-study checkpoints and
|
|
versions unless a new investigation supplies replacement evidence.
|
|
- Keep `website-pages.yml` as the sole, manual production publisher for
|
|
Cloudflare and Pages. Default to `both`: both hosts receive the same verified
|
|
artifact and pass the published-commit check. Use `pages` only when explicitly
|
|
requested while Cloudflare credentials are being configured. Follow the
|
|
website README.
|