Lingui CLI localization helps JavaScript and React teams turn source-language messages into reviewable translation catalogs and compiled language bundles. This guide explains lingui extract, lingui extract-template and lingui compile, including how teams use catalog files, strict checks and TypeScript output to keep a multilingual application coherent across releases.
Developers looking for a Lingui CLI extraction tutorial often discover that a successful compile is not the end of translation work. A catalog may hold obsolete messages, a target-language string may omit a variable, or a screen may fail to load the intended locale despite correct source files. The reliable approach is to distinguish extraction, translation review, build packaging and runtime behavior.
The tutorial is written for a worldwide audience using web applications in multiple scripts and grammatical systems. It covers project configuration, source message context, catalog review, plural handling, TypeScript integration, CI failure analysis, Unicode rendering, accessibility, production smoke tests and troubleshooting without confusing message management with automatic translation.
- Use
@lingui/cliand version-pinned scripts so extraction and compilation are reproducible. - Extract source messages, review catalog diffs and keep translator context alongside message meaning.
- Use
lingui extract-templatewhere the application’s fallback design depends on the template. - Compile approved catalogs for production, selecting strict and TypeScript-related options as appropriate.
- Test the complete user task in each locale, including missing strings, plural values and right-to-left content.
What the workflow does and what it cannot prove
The main distinction is between controlled technical transformation and meaningful communication. Lingui CLI can perform documented file operations, but a multilingual product also needs correct intent, reviewable context, accessible design, stable release provenance and human acceptance. A tool can pass all of its own checks while a user still misunderstands a payment, safety warning or irreversible action. The objective is not more files; it is an interface that people can understand and use in the language they selected.
A practical reading order is to understand the source messages first, establish the command-line inputs and outputs, inspect the target catalogs, run structural validation, render the result and finally verify the complete user journey. For a small project, these stages can be completed by a few people; in a large organization, they should have documented handoffs. Either way, every transition needs evidence that the correct version moved forward.
Know what Lingui contributes
Lingui joins developer-authored messages with translation catalogs and runtime usage. Its CLI handles extraction, template generation and compilation. The framework helps enforce a consistent workflow, but it does not certify the linguistic meaning of a translated sentence.
A team building a booking interface can tag source copy, collect messages for translators, compile selected locales and render them in the product. Each stage leaves an artifact the reviewer can inspect.
Common failure and why it matters
The presence of a generated catalog is sometimes mistaken for evidence of translation coverage; messages in source and correct target-language words are not the same thing.
Practical verification
Identify which library or macro introduces translatable text, which team owns catalog updates and which runtime path loads the compiled language.
A useful review exercise at this stage is to take a real feature that depends on know what lingui contributes, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Install a repeatable local CLI
The official documentation installs @lingui/cli as a development dependency. Script aliases such as "extract": "lingui extract" and "compile": "lingui compile" make the workflow part of the repository.
A teammate cloning the project should be able to install dependencies from the lockfile and run the same extraction command without guessing a package version.
Common failure and why it matters
An unpinned global CLI may behave differently from the build runner, producing an unexpected catalog diff or compilation option error.
Practical verification
Keep versions, scripts and CI instructions together, and document upgrades by showing the changed catalog and build output.
Draw the source-to-catalog boundary
Source components contain the messages the product intends to display, while catalogs contain locale-specific renderings. A source edit should trigger extraction and an explicit review of changed catalog entries.
An engineer revises a ‘Reserve’ button to ‘Confirm booking’. The message ID or associated context needs assessment because translators may have rendered the earlier word as a provisional hold.
Common failure and why it matters
A simple text change can alter a legal or commercial action. Carrying an old translation forward without meaning review risks telling the user the wrong thing.
Practical verification
Treat the source wording, description, and relevant action state as a unit during translation handoff.
Use extraction as a source inventory
lingui extract scans configured sources and creates or updates message catalogs. Interpret its result as a current view of declared messages, not as an infallible list of everything visible in the running UI.
Compare the extracted catalog to a list of product surfaces such as onboarding, checkout, account recovery, email notifications and shared widgets.
Common failure and why it matters
Hardcoded strings and third-party interface text may fall outside configured extraction. A clean CLI exit can coexist with untranslated parts of a screen.
Practical verification
Run a systematic UI inventory and use source review to catch strings that were not marked for localization.
A useful review exercise at this stage is to take a real feature that depends on use extraction as a source inventory, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Build a practical catalog configuration
The application should define its locales and catalog locations clearly so that extraction and compilation refer to the same logical resources. A discoverable configuration reduces mistakes as the number of languages grows.
An application may organize per-locale catalogs around a shared product domain and use separate files for a large admin panel if the project intentionally supports that arrangement.
Common failure and why it matters
A mismatched path can leave a target catalog unused or import the wrong compiled bundle. Neither error requires a bad translation to create a visible defect.
Practical verification
Check each configured locale’s source input, generated output and runtime import against a project-level manifest.
Write complete messages in source
Complete sentences are safer than concatenated translated fragments because grammar and word order vary across languages. Variables should be explicit and their intended values documented.
Model ‘You have {count} unread alerts’ as one message rather than combining three smaller strings. This gives a translator room to adjust grammar.
Common failure and why it matters
A fragment that appears harmless in English can prevent correct agreement or punctuation in a target locale, especially where nouns inflect with numbers.
Practical verification
Review new message patterns for completeness before localization and discourage runtime concatenation of translated fragments.
Preserve grammatical context
A translation memory or dictionary cannot infer every UI meaning. A source message’s description should explain who is speaking, what action occurs and which data will be inserted.
Use distinct context for ‘Charge’ as a payment operation and ‘Charge’ as battery level. Where necessary, keep separate message IDs rather than reusing English text.
Common failure and why it matters
A translator choosing the wrong sense of a short term may create an interface that is fluent but functionally wrong.
Practical verification
Ask reviewers to read the message inside the actual screen and test the outcome of clicking the corresponding control.
A useful review exercise at this stage is to take a real feature that depends on preserve grammatical context, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Handle plurals as language decisions
Plural forms are locale-sensitive; the number zero, one, two and larger quantities may need different forms. The application supplies values while catalog wording expresses the language’s rules.
Test a message about items in a basket at zero, one, two, five and a large count. Focus on readable grammar and whether the amount remains attached to the right noun.
Common failure and why it matters
A source-language singular/plural pair is not a universal rule. Hardcoding English conditions into messages can make some targets unnatural or wrong.
Practical verification
Use the target locale’s plural syntax and render multiple real values during review instead of checking a single screenshot.
Choose stable message identity
IDs and source messages have lifecycle consequences. Stable identity helps preserve legitimate reviewed translations, but retaining an ID after a meaning change may wrongly recycle old wording.
If the same ID changes from ‘Archive project’ to ‘Delete project permanently’, treat all target entries as needing fresh review, even if the catalog system retained their previous strings.
Common failure and why it matters
An apparently efficient ID reuse may make translation QA less reliable than a properly updated catalog because the old text looks complete.
Practical verification
Document the difference between cosmetic copy edits and changes of action meaning, and make meaning changes visible in pull-request reviews.
Use template generation intentionally
The documented lingui extract-template creates a .pot template. The documentation describes its role in a fallback workflow when catalogs are not synchronized with source messages.
Run template generation in the build stage where the application’s integration requires that fallback, and understand whether the generated artifact should be committed or generated afresh.
Common failure and why it matters
A missing template can conceal a source string or cause fallback behavior to differ between a local environment and a production build.
Practical verification
Simulate a temporarily missing translation and observe the actual user-facing fallback, rather than assuming that a template always prevents a blank label.
A useful review exercise at this stage is to take a real feature that depends on use template generation intentionally, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Review PO files as structured resources
PO catalogs can carry message identity, translations and review metadata. They are not ordinary prose documents where arbitrary reformatting is harmless. Translators must preserve placeholders and special syntax.
Compare a source message with its target PO entry, checking variable names, punctuation, intended meaning and whether a reviewer has seen the latest source wording.
Common failure and why it matters
A translation editor may accidentally change a message identifier or strip a formatting token; the file may look human-readable but no longer match runtime calls.
Practical verification
Use a translation-aware editor or careful diff review, and compile the result before approving it.
Track obsolete and unfinished work
Source changes can leave outdated or unfinished entries. The team should distinguish deliberately retired messages from valid messages still awaiting translation and from reviewed target text.
For a deleted account-recovery step, mark the old message as removed from the active product path. For a newly added payment error, record that the target language still needs review.
Common failure and why it matters
Declaring all untranslated entries ‘done’ by copying the source hides localization debt. Conversely, deleting every historical entry can make review history harder to follow.
Practical verification
Agree on lifecycle labels and a documented cleanup cadence so catalog maintenance is predictable rather than improvised.
Compile for the intended runtime
lingui compile converts message catalogs into minified JS or TS artifacts that the application can consume. Run it after catalog reviews so the shipped output matches approved text.
Compile a single target locale in development, render its core flows and compare the imported bundle to the intended catalog revision.
Common failure and why it matters
A project can compile the right catalog yet deploy an older built file from cache. It can also compile a locale that the app never loads.
Practical verification
Use clean builds and an output manifest. Confirm runtime imports and application locale selection before declaring the release successful.
A useful review exercise at this stage is to take a real feature that depends on compile for the intended runtime, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Use strict mode carefully
The CLI documents lingui compile --strict. Strict compilation can enforce a higher completeness expectation; teams should understand their chosen release policy rather than disabling strictness when a target is unfinished.
A product may require complete German checkout translations before launch while permitting a noncritical internal dashboard to fall back to English temporarily.
Common failure and why it matters
Treating every missing key as equally dangerous can halt development without improving safety; ignoring missing consent and payment strings is worse.
Practical verification
Define critical flows and target-language launch criteria, then align strict checks and human review with those criteria.
Generate TypeScript support where useful
The documented --typescript compile option can produce TypeScript-related compiled catalogs. Type information helps catch mismatches between source modules and application imports.
In a typed application, make the output path and compilation mode part of normal build scripts. A reviewer should know whether generated types are checked in or produced by CI.
Common failure and why it matters
Types cannot prove cultural correctness or guarantee that a localized button means the intended action; they address a different class of integration mistakes.
Practical verification
Treat typing, syntax checks, linguistic review and accessible rendering as complementary tests rather than competing substitutes.
Use watch mode for development, not approval
Lingui’s compilation CLI documents a watch option for development. It helps shorten feedback loops while copy and UI are changing, but a live watcher is not a reproducible production build.
A developer can watch catalog changes while testing a language switch, then run a clean explicit compile before submitting the release.
Common failure and why it matters
A browser may display an old hot-reloaded bundle or a partial build even when the watched terminal appears active.
Practical verification
Repeat clean production compilation and runtime tests in CI, without relying on the state of a developer’s watch process.
A useful review exercise at this stage is to take a real feature that depends on use watch mode for development, not approval, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Control generated files and versioning
The source code, catalogs and compiled bundles each have distinct change histories. Choose a clear policy on which files are canonical and which are reproducible outputs.
If compiled bundles are generated during deployment, ensure the source catalog revision is included in the build and the output is deterministic enough for review.
Common failure and why it matters
Committing some generated outputs but not others can let stale language bundles persist. Ignoring every file without documenting generation can also break deployment.
Practical verification
Record where approved translations live, how artifacts are produced and how their versions are traced to a source commit.
Design useful CI gates
An effective pipeline can extract messages, compare catalog diffs, inspect approved translation state, compile all required locales and render critical flows. The order gives actionable failure information.
When a new feature adds one plural message, CI should tell reviewers whether extraction changed the catalog, which locales are incomplete and whether compilation succeeded.
Common failure and why it matters
A single giant command may hide whether the failure comes from configuration, a bad message token, untranslated copy or application import.
Practical verification
Keep jobs or logs phase-specific and include locale and message identity in reviewer-facing errors without leaking confidential data.
Check interpolation and unsafe content
Variables in localized text should pass through the framework’s intended rendering path. Do not treat external user input as trusted translation markup.
Render a welcome banner with a synthetic name that contains an ampersand, quote and non-Latin character. Confirm the label remains readable and is not interpreted as injected HTML.
Common failure and why it matters
Ad hoc replacement or raw markup processing can cause rendering defects or security risks even with grammatically correct catalog entries.
Practical verification
Use safe rendering conventions, verify variable types and exercise representative inputs before production deployment.
A useful review exercise at this stage is to take a real feature that depends on check interpolation and unsafe content, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Verify writing direction and typography
A compiled locale file does not guarantee correct right-to-left layout, shaping or font fallback. Those depend on markup, CSS, operating system and available fonts.
Test an Arabic interface containing an email address, account number and English brand name. Observe the reading order and punctuation around mixed-direction fragments.
Common failure and why it matters
Without isolation or careful layout, a value can appear visually reordered and make users copy the wrong identifier.
Practical verification
Check bidi behavior on the actual device and use appropriate direction settings instead of reversing strings manually.
Include accessibility text in the language inventory
Tooltips, hidden labels, validation summaries, focus announcements and document titles may be experienced by users even if they are not prominent in screenshots.
Review a reset-password flow with only keyboard and screen-reader navigation, including inline errors and success alerts.
Common failure and why it matters
A localized visual heading beside an English accessible label creates conflicting instructions, especially for people using assistive technology.
Practical verification
Inspect semantic labels, focus transitions and dynamic messages in every required locale and test at least one complete accessible task.
Prepare a realistic release smoke test
A language is ready only when critical screens load their intended catalogs and actions work. Test with fresh accounts and representative data, not just the home page.
Run onboarding, account recovery, data export, a purchase cancellation and a permission error in the target locale. Check that routing and state changes preserve the chosen language.
Common failure and why it matters
A locale that works during a static preview can fail after authentication redirects, deferred loading or navigation to another route.
Practical verification
Record each tested path, locale and observed result; hold the release when a core instruction is missing or misleading.
A useful review exercise at this stage is to take a real feature that depends on prepare a realistic release smoke test, compare the source intent with the target-language experience, and record an observable pass-or-fail result. Ask what the user would conclude before and after clicking the relevant control. Preserve the smallest reliable test as a fixture for future releases. This connects language quality with actual product behavior rather than treating a successful command as the final definition of correctness.
Treat translator communication as product work
Developers should explain the intended action, audience and limitations of each message. Translators should be able to report ambiguous source copy rather than guessing.
For a warning about irreversibility, show the confirmation screen and tell reviewers whether an action can be undone. Better source wording may resolve ambiguity across every language.
Common failure and why it matters
When feedback is handled as ‘just a translation issue’, a genuinely unclear product decision may persist in all locales.
Practical verification
Route meaning questions to the product owner and update source context so the correction benefits future translations.
Observe and repair post-launch defects
After deployment, customers reveal gaps no pre-release suite catches. Useful reporting identifies locale, screen, action and expected meaning without collecting unnecessary personal information.
A user reports that a translated button appears to promise a refund but instead applies credit. Reproduce the task, correct the source or target as appropriate, and retest.
Common failure and why it matters
Fixing only the visible label can leave the email confirmation and accessibility announcement inconsistent with the actual business action.
Practical verification
Maintain a locale-aware defect log and include repeatable tests in the next release to prevent regression.
Worked walkthroughs: three different defects and how to fix them
Worked project: subscription renewal
A product offers English, French and Korean. A developer marks the renewal prompt and all currency-bearing notices for localization, extracts catalogs, and requests translation review using screenshots and product-policy notes. The reviewer confirms that a renewal date, price and cancellation window mean the same thing in each locale. Compile the selected catalogs, check the runtime import and render the screen with representative prices and long account names. Repeat the flow in a narrower mobile viewport. The project is not approved merely because every PO entry has text: the user must understand the commitment before confirming payment.
For a disciplined review, write down the intended result, the exact source revision, the target locale and the visible evidence. Run the described workflow on a disposable test account with synthetic data; compare what the interface communicates with what the system actually does. If the problem is technical, repair the file or configuration contract; if the wording is misleading, revise the translation and seek language approval. A corrected build should pass both kinds of inspection before returning to production.
Worked project: a catalog drift incident
A team changes an account deletion flow but forgets to rerun extraction before packaging the Italian catalog. The old translation is still structurally valid. The release check should catch that the generated catalog and source commit are out of step. Re-extract, compare source meaning and mark the old target wording for re-review. Compile only after the corrected translation is accepted. Verify both the on-screen instruction and follow-up email. This case demonstrates why human review and source-revision tracking are necessary even when strict compilation passes.
For a disciplined review, write down the intended result, the exact source revision, the target locale and the visible evidence. Run the described workflow on a disposable test account with synthetic data; compare what the interface communicates with what the system actually does. If the problem is technical, repair the file or configuration contract; if the wording is misleading, revise the translation and seek language approval. A corrected build should pass both kinds of inspection before returning to production.
Worked project: a missing locale bundle
A new locale appears in a configuration file, but the application deploys without its compiled bundle. The fallback may make the interface seem partially usable while hiding the underlying packaging error. Inspect the configured locales, source catalog path, compiled output path and runtime imports as separate checkpoints. Rebuild from a clean checkout, compare the expected artifact manifest, and navigate through the intended locale route. Only then classify the issue as resolved. This is a delivery defect, not a reason to rewrite the translated text.
For a disciplined review, write down the intended result, the exact source revision, the target locale and the visible evidence. Run the described workflow on a disposable test account with synthetic data; compare what the interface communicates with what the system actually does. If the problem is technical, repair the file or configuration contract; if the wording is misleading, revise the translation and seek language approval. A corrected build should pass both kinds of inspection before returning to production.
A release checklist that protects readers
- Freeze the source-message revision, the language list and the build tool version before collecting final approvals.
- Check that extraction covers every intended UI surface, including errors, hidden labels, emails and permission states.
- Review meaning, terminology, placeholders, variable types, punctuation and all conditional branches for each target locale.
- Compile from a clean checkout and confirm that the expected per-locale artifacts are present and loaded at runtime.
- Exercise realistic numbers, dates, names, long strings, Unicode characters and right-to-left text where relevant.
- Test the entire task with keyboard navigation, assistive technology and small screens, not merely static screenshots.
- Record approvals, defects, deployment revision and rollback steps so corrections can be traced without guesswork.
A release decision should be reversible and specific. If only one language has a harmful or misleading translation, the team should be able to hold that locale or revert its resources without discarding correct source code or other approved languages. Keep the change log explicit: which message, which locale, which screen, and which expected user action changed? This discipline is especially important for payments, consent, health notices, account deletion and security alerts, where unclear wording can have consequences outside the interface.
Frequently asked questions
What does Lingui CLI actually do?
It extracts message definitions from source, helps maintain catalog resources, generates templates when configured, and compiles translations into application-consumable bundles. It does not automatically guarantee faithful translation.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
What is the difference between extract and compile?
Extraction updates or generates message catalog material from source code. Compilation takes approved catalog entries and produces the output consumed by the running application.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
Why are PO catalogs useful?
They provide a structured place for message identity and translated text. Translators can review changes while developers preserve technical tokens and message lifecycle.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
When should strict compilation be used?
When a release policy requires a high level of translated-message completeness. Teams should choose launch gates deliberately, particularly for critical payments, permissions and security messages.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
What is extract-template for?
The documented command creates a POT source template. In supported setups it can help fallback behavior for messages missing from synchronized catalogs.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
Does the TypeScript option prove correctness?
No. It helps type-related build integration but cannot prove linguistic accuracy, legal nuance, accessibility or visual rendering.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
How should plurals be tested?
Use representative quantities for each locale and confirm both argument handling and grammar. The plural categories of the source language are not universal.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
Can translation fragments be combined?
Avoid building sentences by concatenating translated pieces. Translators need complete messages to place words and punctuation correctly.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
What causes stale translations?
Source messages change without extraction or review, or an older compiled artifact reaches deployment. Track source commits, catalog revisions and output artifacts together.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
How do we test a new language?
Verify catalog coverage, compile from a clean environment, select the locale in the running app, complete critical tasks and test Unicode, accessibility and direction-sensitive layouts.
The practical test is not whether the term sounds technical; it is whether a reviewer can trace the message from source intent to the exact visible screen and reproduce its behavior. When the answer depends on package versions, use the official command reference for the version pinned in the project and preserve a small regression example before deploying a change.
Next reading and original documentation
Official references are best used to confirm command syntax, supported flags and version-specific behavior. The explanations above focus on applying those commands to reliable translation outcomes; the linked documentation provides the authoritative details for each tool release.
Final perspective
Professional translation is a chain of accountable decisions. Collect the right source message, describe the real user action, preserve structure, check the language in context and prove that the compiled interface behaves correctly. Lingui CLI is most useful when it makes these steps repeatable and auditable. The benefit for international readers is not a cleverer automation pipeline; it is being able to understand what a product says and trust what happens next.