lingo extract
Generate source JSONC and TypeScript declarations from explicit translation calls.
lingo extract gives explicit React messages a catalog identity. It scans TypeScript/TSX calls, writes source JSONC and declarations locally, and preserves metadata connecting each entry to its source. It does not rewrite arbitrary JSX or request translations.
In a configured React component, a supported call looks like this:
const l = useLingo();
const label = l.text("Place order", { context: "Checkout submit button" });Run extraction from the project root:
lingo extract --src src --source-locale enWith default paths, inspect locales/en.jsonc and lingo.d.ts. The source catalog records message values, context, and source locations. The React quickstart supplies imports and provider setup for the component.
Options #
| Option | Default or effect |
|---|---|
--src <path> | Scan directory, default src. |
--source-locale <locale> | Output source locale, default en. |
--out <path> | Overrides configured i18n.messagesPath, then default locales. |
--types <path> | Overrides configured i18n.typesPath, then default lingo.d.ts. |
--check | Compare generated bytes with disk without writing. |
Paths resolve from the nearest project root. Source locale does not inherit localization sourceLocale; specify another language explicitly. Normal writes create declaration directories.
What the scanner recognizes #
The scanner recognizes text, rich, plural, and select on variables assigned from useLingo or createLingo, plus conventional l and .l receivers. It accepts string literals, templates without expressions, and static form objects.
Dynamic messages have no stable extractable source. Destructuring a factory result loses the tracked receiver shape and warns. Declaration files, dotfiles/directories, and node_modules are excluded. When no TS/TSX files exist, extraction reports that and returns without a result; a successful process exit does not prove messages were found.
Review identity and merge behavior #
Keys derive from source and context. A wording or context change can create a new identity; values substituted at runtime do not. Collisions fail extraction and need disambiguating context.
Extraction merges with the existing source catalog: it preserves current values, updates context/source metadata, adds new entries, and marks absent messages as orphaned. Sorted output is deterministic. Inspect warnings before treating an orphan as an intentional removal from the application.
Check or translate the catalog #
lingo extract --check compares both catalog and declaration bytes without writing. lingo check additionally examines context, orphans, and discovered targets.
For translation, add the actual .jsonc path to files[], authenticate, link, and use initial lingo push --backfill-missing --wait. Later changes use plain push. Changing extraction paths does not change file configuration automatically.
Load the result with a JSONC-compatible loader and the catalog metadata policy. The provider expects a string map; neither a raw file path nor an ordinary JSON import completes that conversion.