`lingui compile --strict` semantics do not match `extract` "Missing"

[yslpn]

Description

There is an inconsistency between:

• the Missing counts reported by lingui extract
• the documented behavior of lingui compile --strict
• the actual runtime behavior when fallbackLocales are configured

The CLI docs currently say that --strict will:

Fail if a catalog has missing translations.

At the same time, the config docs say that fallbackLocales are used when a translation for a locale is missing.

Today these two concepts do not line up clearly:

• lingui extract reports Missing based on raw catalog entries with empty translations
• lingui compile --strict appears to validate the resolved result after fallbacks are applied

Because of that, a locale can still show Missing > 0 in extract stats, while lingui compile --strict exits successfully.

This is especially confusing in CI for teams that:

• use fallbackLocales at runtime
• still want to fail builds until each locale catalog is fully translated

Related but distinct from #2195: that issue asks for a dedicated check command without writing files. This issue is about the current semantic mismatch between documented strict-mode behavior and what the CLI actually validates.

Verifications

• I've checked the docs and this isn't covered there.
• I've searched existing issues on GitHub.

Reproduction Steps

Documentation references:

• CLI strict mode: https://lingui.dev/ref/cli#compile-strict
• fallbackLocales: https://lingui.dev/ref/conf#fallbacklocales
• sourceLocale: https://lingui.dev/ref/conf#sourcelocale

lingui.config.js

export default {
  locales: ["en-US", "en-GB"],
  sourceLocale: "en-US",
  fallbackLocales: {
    default: "en-US",
  },
  catalogs: [
    {
      path: "<rootDir>/{locale}",
      include: ["<rootDir>"],
      exclude: [],
    },
  ],
}

en-US.po

msgid "Hello"
msgstr "Hello"

en-GB.po

msgid "Hello"
msgstr ""

Run:

lingui extract

Result:

Catalog statistics for {locale}:
┌────────────────┬─────────────┬─────────┐
│ Language       │ Total count │ Missing │
├────────────────┼─────────────┼─────────┤
│ en-US (source) │      1      │    -    │
│ en-GB          │      1      │    1    │
└────────────────┴─────────────┴─────────┘

Then run:

lingui compile --strict

Current result:

Compiling message catalogs…
Done in <n>ms

The process exits with code 0.

Expected Behavior

The current behavior should be clarified or changed so that the semantics are consistent.

One of these should happen:

1. lingui compile --strict should fail when locale catalogs still contain raw missing translations, matching the Missing counts reported by lingui extract.
2. If lingui compile --strict is intentionally defined as "fail only after fallback resolution", the docs should say that explicitly, because the current --strict wording reads much broader.

Without that clarification, extract and compile --strict suggest different answers to the question "does this locale still have missing translations?"

Macro Support

Not using macro

Lingui Version

@lingui/cli 6.0.0-next.3 (current repository state)

Babel Version

N/A

Framework

CLI only / no framework

[timofei-iatsenko]

@yslpn, thanks for looking into this. In my opinion, fallbackLocales is a pretty confusing feature overall. Unfortunately, we don't have visibility into how many users are actually utilizing it - maybe it's time we consider adding anonymous usage statistics to the CLI?

I'm not sure which of your proposed options is best yet. We haven't received much feedback on this, and I doubt we'll get enough via GitHub issues alone to make a definitive call.

Personally, I think fallbacks should be handled at the TMS level, with catalogs being 100% populated. This aligns more closely with your first proposal.

[yslpn]

@yslpn maybe it's time we consider adding anonymous usage statistics to the CLI?

It would be better to create this as a separate issue for it.

I'm not sure which of your proposed options is best yet. We haven't received much feedback on this, and I doubt we'll get enough via GitHub issues alone to make a definitive call.

Personally, I think fallbacks should be handled at the TMS level, with catalogs being 100% populated. This aligns more closely with your first proposal.

I think I’d prefer --strict to match the current meaning of missing in extract.

That would likely be a breaking change for users who rely on fallbackLocales together with compile --strict, but on the other hand it would mostly align the actual behavior with what the docs already say today.

I also think this matters for check in #2195: it would be much easier to understand the CLI if extract, compile --strict, and check all used the same definition of "missing translations".

If we agree on that direction, it would be great to land it in v6. I’d be happy to work on it.

[timofei-iatsenko]

@yslpn yes, i agree

[timofei-iatsenko]

I re-read a description one more time and checked the code and now have some doubts, to solve them could you clarify what you mean by:

This is especially confusing in CI for teams that:

use fallbackLocales at runtime

How fallbackLocales could be used on runtime?

[yslpn]

I re-read a description one more time and checked the code and now have some doubts, to solve them could you clarify what you mean by:

This is especially confusing in CI for teams that:
use fallbackLocales at runtime

How fallbackLocales could be used on runtime?

You're right, runtime was not the best wording.

What I meant is that fallbackLocales affect the app’s runtime-visible behavior via the compiled catalogs: compile can fill missing entries from fallback locales, so the running app serves those fallback strings even though the raw locale catalog still has empty translations.