Extract, Compile, and Verify

Treat the pipeline as three separate stages

1. Extract (lingui extract)
   • message descriptors are found and written to catalogs
2. Compile (lingui compile)
   • catalogs are prepared for runtime use
3. Verify
   • the app renders the expected translated output

Debugging is much easier when these are treated separately.

Transform and extraction are separate concerns

Every file type that uses Lingui macros needs two things configured independently:

• a build transform that compiles macro calls into runtime calls at build time
• an extractor that teaches lingui extract how to find message descriptors in source files

These serve different phases. A successful build does not mean extraction is working - the extractor runs separately via the Lingui CLI and must be configured on its own.

File type	Build transform	Extractor
.svelte	lingui-for-svelte/unplugin/vite	lingui-for-svelte/extractor
.astro	lingui-for-astro/integration	lingui-for-astro/extractor
.ts, .js, .tsx, .jsx	unplugin-lingui-macro/vite	@lingui/cli/api/extractors/babel (default export)

In a mixed project, both extractors must be listed. For example, a SvelteKit project with shared utility files in plain TypeScript:

lingui.config.ts

import { defineConfig } from "@lingui/conf";
import babelExtractor from "@lingui/cli/api/extractors/babel";
import { svelteExtractor } from "lingui-for-svelte/extractor";

export default defineConfig({
  locales: ["en", "ja"],
  sourceLocale: "en",
  catalogs: [{ path: "src/lib/i18n/locales/{locale}" }],
  extractors: [svelteExtractor, babelExtractor],
});

Without babelExtractor, any t call in a .ts file will compile correctly at build time but will not appear in the extracted catalog.

Which tools are responsible for what

• lingui-for-svelte and lingui-for-astro
  • framework syntax support and framework-specific extractors
• unplugin-lingui-macro
  • plain JS and TS Lingui macro transform
• Lingui CLI
  • extraction and catalog compilation

Recommended habit

After adding a new syntax pattern, verify all three:

• it builds
• it extracts
• it renders correctly

Do not assume that a successful build automatically means extraction is correct.