Glossary — English terminology#

This file is the single source of terminology for the English documents, exactly as zh/GLOSSARY.md is for the Chinese ones. Two documents written a month apart should not disagree about whether the thing is a mailbox or an account, a folder or a directory; this is where those choices are written down, so a later edit can be measured against them instead of guessed at.

The Chinese file is not a translation of this one: it records the same decisions and adds the Chinese rendering of each term, and it is the authority for anything a translator has to decide. A term changed here has to change in both files — tools/check-docs.mjs and tools/check-zh.mjs are what notice when the pair drifts.

1. Literals that are never spelled differently#

Keep these exactly as the code spells them, in backticks, including case and punctuation: configuration keys (server.hostname, api.jwt_secret), environment variables (DATABASE_URL, FERROMA__API__WEBMAIL_DIR), commands (ferroma database init), HTTP methods and paths (POST /api/v1/storage/gc), protocol keywords (EHLO, MAIL FROM, IDLE), reply and status codes (550 5.1.1, 426 Upgrade Required), Rust types (FerromaError::MailboxFull), database objects (change_log, rfc_message_id, TIMESTAMPTZ), JSON field names, paths (/var/lib/ferroma), and RFC numbers (RFC 5322, never "the RFC 5322 standard"). The exhaustive list, with the Chinese renderings that go with it, is zh/GLOSSARY.md §一.

2. Canonical terms#

"Not" is what to avoid; it is not always wrong English, only a second name for one thing, which is what this table exists to prevent.

3. Style#

• English is the default. README.md, CHANGELOG.md, TODO.md and docs/*.md are
  the primary text; the *_zh.md and docs/zh/* files mirror them and say so.
• Sentence-case headings, one # per file. Headings are not renamed to fix
  terminology: other documents link to their anchors, and tools/check-docs.mjs fails
  on a link whose anchor is gone.
• Identifiers, paths, keys and commands go in backticks; prose does not.
• Em dashes are spaced: text — like this.
• Serial comma in a list of three or more.
• Quantities take a space and a unit: 10 MB, 14 days, 86400 s; time is UTC.
• A term is introduced once as "Chinese (English)" only in the Chinese files; English
  text uses the English term alone.

4. Cross-references#

• An English document links to a sibling by file name: [smtp.md](smtp.md). A Chinese
  document links to its Chinese sibling; repository paths climb one level further
  (../../crates/), because the mirrored file is one directory deeper.
• Every pair keeps the same headings and the same number of code fences
  (tools/check-zh.mjs), and every link and anchor resolves (tools/check-docs.mjs).
• Text that leaves the repository — dockerhub.md, pasted into the
  Docker Hub page — uses absolute https://github.com/z1HwanG/Ferroma/… URLs, because
  a relative link cannot resolve outside a checkout.

5. Keeping the pair in step#

node tools/check-docs.mjs              # links, anchors, the bilingual Docker Hub artifact
node tools/check-zh.mjs                # heading/fence parity and terminology across the pair
node tools/build-site.mjs              # render docs/ the way a reader will see it
node tools/site-check.mjs              # no unrendered markdown, no link without a target
node tools/check-deploy.mjs            # the deployment path the docs describe

All of them run in CI before a release image is built (.github/workflows/docker-publish.yml), so a document that drifts fails the release rather than the reader.