0148. duolith locales extract adds a key for each untranslated text, named after its page
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-14
- Decided by: wave 5 developer tools agent (domain F), pending Mik
- Planning item: v1 gap audit, developer tools: "string extraction"
Context
Translation (decision 0072) reads keys from locales/<locale>.json. An app that starts with plain text in its markup needs a way to move that text into catalogues, without writing every key by hand.
Decision
duolith locales <check|extract> [project] [--rewrite] [--json]:
- **
check** runs the build's catalogue checks without building. - **
extract** reads the text in markup and in the attributes people read (label,placeholder,title,alt, and the others the build reads), in pages and components.- Each text gets a key
<file>.<words>, such asindex.add_a_todo. - Each missing key is added to every catalogue, with the text as its value.
locales/en.jsonis made when there is no catalogue. - Keys already used, and their values, are never changed.
- Each text gets a key
- **
extract --rewrite** also replaces each extracted text with{t("key")}and importstwhere the page does not.
--json prints spec/schemas/cli/locales.schema.json.
Alternatives considered
| Option | Why not |
|---|---|
| Keys from a hash of the text | Unreadable in the catalogue and in review. |
| Rewrite by default | Rewriting markup is a bigger change than adding keys. It is opt-in, so a person can review the catalogue first. |
| Only English catalogues | Every catalogue would then miss keys, and check would fail on them. Adding the key with the source text keeps each catalogue complete, ready to translate. |
Consequences
- Text built at runtime (template strings, expressions) is not extracted. It needs a
t()call written by hand. crates/cli/src/locales_extract.rshas tests, andpackages/testing/test/cli-json.test.tschecks the JSON.