Writing user-facing text

Every sentence a person sees comes from locales/en.json, so the app can be translated and the voice stays consistent. English is never assembled in code.

Where text lives

• UI text: top-level keys ("routes": { "empty": { "title": "No routes yet" } }), read with t("routes.empty.title").

• Text produced in Rust (errors, Doctor, plan steps, menus, notifications, CLI-facing messages from core): under "core". crates/core/build.rs generates one function per message in text::msg, with exactly the message's placeholders as arguments, so a wrong key or missing argument fails to compile:

  "core": { "doctor": { "dnsMissing": { "title": "{hostname} has no DNS record" } } }

  becomes msg::doctor::dns_missing::title(hostname) -> Text.

In Rust

Return a Text, never a String meant for a person. Errors map each variant to its message (engine/planner.rs):

impl UserText for PlanError {
    fn text(&self) -> Text {
        match self {
            Self::NoZone(hostname) => msg::error::plan::no_zone(hostname),
            Self::RouteExists(hostname) => msg::error::plan::route_exists(hostname),
            // …
        }
    }
}

• Errors implement UserText; their Display (English, for logs) comes from it.
• A new core.error.* message also needs an entry in apps/desktop/src/lib/error-help.ts saying how the app helps (fix, link, input or retry); error-help.test.ts fails until it has one.
• Technical values (hostnames, paths, codes) are arguments; msg::raw wraps text shown as it is.
• The UI translates a Text with translate(). The core renders it itself only for native menus, notifications and the CLI.

In React

import { t } from "@/lib/i18n";

<Button>{t("routes.empty.add")}</Button>

• Module-level maps hold message keys (MessageKey) and call t() at render, never at import.
• Write a whole sentence as one message with placeholders; never concatenate fragments.
• aria-labels, placeholders, tooltips and toasts are text too.

Plurals and placeholders

• Placeholders are {name}. Keep their names in every language.
• Counts use CLDR plural suffixes with {count}: "routes_one": "{count} route", "routes_other": "{count} routes". In Rust the generated function takes count: u64 first.

Per-platform wording

A message that names something macOS-specific (this Mac, Finder, the keychain, System Settings, the menu bar, ⌘, Homebrew) needs Windows and Linux wordings as sibling keys: "key@windows" and "key@linux" ("this PC", "File Explorer", "Credential Manager", "Settings", "Ctrl"). The catalog test fails when one is missing.

Voice

Follow DESIGN §10:

• Title case for buttons, menu items and window, sheet and dialog titles ("Add Route", "Check Again"); sentence case for everything else ("No routes yet").
• An action that asks for more before acting ends with "…" ("Delete…").
• Say what happened, why, and what to do next: "Couldn't create app.teispace.com. A record with this name already exists (A 203.0.113.4). Replace it or choose another name."
• Describe outcomes, not internals: "app.teispace.com now points to localhost:3000", not "Ingress updated". Use the product's terms: Route, Domain, Tunnel, Connector, Quick Share, Doctor, Activity.
• No exclamation marks, "Oops", emoji or marketing tone.
• Hostnames in examples use a real-looking domain such as teispace.com.

Check

pnpm --filter @teitunnel/desktop test -- i18n         # catalog checks: keys, placeholders, platforms
pnpm --filter @teitunnel/desktop i18n:missing <lang>  # a translation's missing keys
cargo build -p teitunnel-core                       # regenerates text::msg

Then pnpm verify.