Duolith docs

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 as index.add_a_todo.
    • Each missing key is added to every catalogue, with the text as its value. locales/en.json is made when there is no catalogue.
    • Keys already used, and their values, are never changed.
  • **extract --rewrite** also replaces each extracted text with {t("key")} and imports t where the page does not.

--json prints spec/schemas/cli/locales.schema.json.

Alternatives considered

OptionWhy not
Keys from a hash of the textUnreadable in the catalogue and in review.
Rewrite by defaultRewriting markup is a bigger change than adding keys. It is opt-in, so a person can review the catalogue first.
Only English cataloguesEvery 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.rs has tests, and packages/testing/test/cli-json.test.ts checks the JSON.