RFC: Default value for unsupplied message variables.

[Goodwine]

Motivation & Background

Let's take for example the message Welcome!. When translated to spanish, which is a gendered language like many others, this may be translated to:

• Bienvenida! (femenine)
• Bienvenido! (masculine)
• Te damos la bienvenida! (neutral)

Although we all know in this room that we can always use ICU-select to add gendered variants to this message, app developers may not. In a way, it is possible that EVERY message in the catalog should have ICU-select for gender "just in case". But that's obviously not optimal neither for performance nor for DevEx.

Inspiration: Android's Grammatical Inflection

This idea is inspired by https://developer.android.com/about/versions/14/features/grammatical-inflection, which allows apps to address the user using their preferred profile gender.

In Android, supporting grammatical gender relies on separate resource qualifiers (e.g., es-femenine/strings.xml, es-masculine/strings.xml). Replicating this multi-file approach in LinguiJS (and any other competing localization library) would require generating separate catalog files (es.femenine.po, es.masculine.po, es.po), leading to a combinatorial explosion of catalogs.

Instead of bloating network requests, it would be awesome if the Translators could wrap the entire input message with an ICU-select targeting the user's gender.

For example, following through with the example above, the translators may generate the following catalog:

# Source string: ""
msgid "Welcome"
msgstr "{__gender, select, FEMENINE {¡Bienvenida!} MASCULINE {¡Bienvenido!} other {¡Te damos la bienvenida!}}"

Since this is a valid ICU expression, lingui compile actually compiles it readily and without a problem.

The Core Problem

App developers will use <Trans>Welcome</Trans> without passing values={{ __gender: userGender }} because the source string is not an ICU expression, and they were not aware that it would be "genderified".

At runtime, evaluating this target __gender is missing from the payload, so the other branch is chosen.

Generalizing

At its core, this problem extends beyond grammatical gender. As I was writing this RFC, I realized that the the real problem is an undefined variable that might represent a "global" state, for which a default value could be provided. This allows translators, as the experts in their language, to include the variable if they deem it appropriate.

Obviously, this would not be an open-ended set of variables. As the use case has to be extremely specific, it should be possible to configure a set of variables whose default values can be configured to be guaranteed to be provided at runtime without the app developer having to explicitly declare it on the source code.

Some use cases which may be addressed by this feature:

• Grammatical Gender: {__gender, select, ...} based on active user profile.
• Dynamic Brand / App Context: {__appName} or {__companyName} in white-labeled applications.
• Global Constants: {__supportEmail} or {__currentYear} in common footer/legal templates.

Rather than building a specific, intrusive compiler feature for gender, LinguiJS can handle all of these gracefully by providing a missing variable resolution contract at runtime. Which I believe simplifies the problem and avoids hardcoding for one specific use case.

---

Goals

• A simple callback or key-value dictionary to intercept and supply missing message variables.
• Avoid breaking changes in the existing JSON catalog format.
• Allow translators to introduce (predefined) target variables without forcing front-end developers to retroactively update call-sites (or even realizing their addition).
• If a caller explicitly passes values={{ __gender: 'FEMENINE' }}, the caller's value always takes precedence over fallback resolvers.

---

Design

API

Add a defaultValues option (or something like that) to lingui.config.ts configuration file, and accept an object map that supports both static values and dynamic getter functions:

export default defineConfig({
  // ...
  defaultValues: {
    __gender: () => (typeof window !== 'undefined' ? window.__USER_GENDER : 'NEUTRAL'),
    __appName: 'MyCoolApp',
  },
});

Defined as:

defaultValues: DefaultValues;

interface DefaultValues {
  [value: string]: (()=>string)|string
}

---

2. Runtime Resolution Pipeline

When i18n._(id, values) evaluates a compiled ICU message, variable lookup follows a clean order of precedence:

• Is values[varName] defined?
  • YES: Use values[varName]
  • NO: Is defaultValues[varName] defined?
    • YES: return typeof defaultValues[varName] === 'function' ? defaultValues[varName]() : defaultValues[varName]
    • NO: return undefined

Implementation (@lingui/core)

I tried looking at how to add a config, but I could not get it to work while hacking away at `node_modules`  😅

---

Caveats

SSR

The resolver might resolve a value available exclusively during runtime. The response renders correctly when the default value is a static string or a function with a value resolvable during SSR. However, a value accessible only at runtime (e.g. window.MY_VALUE), the UI would "flash" the original message before switching to the new one.

By Convention Only

Supported default values will be limited to a specific subset of pre-configured options. Translators (or the scripts responsible for generating translated catalog files) need to be mindful of this feature, as it may introduce an additional step into the localization pipeline. However, this functionality is entirely opt-in and maintains 100% backward compatibility.

---

Alternative Considered

While we're pursuing this feature to improve the experience for non-male users (given that "neutral" forms in gendered languages typically default to the masculine form) we found a way to implement it by adding a plugin that "captures" ALL <Trans> or t() call during build-time. This plugin would "inject" our target variable into EVERY regardless of whether it's actually used. The performance impact was minimal, but the approach felt too hacky. I believe this feature may be of broader interest to others.

[Goodwine]

Note that if accepted, I can look to contribute. I actually looked into making a PR, but as stated above I could not find how to add the new option heh. I can have a better look later tho

[andrii-bodnar]

Thanks for raising this! The frustration behind it is real, and it's close to something we've been exploring from another angle in #2517.

My main concern is that the contract isn't discoverable in either direction. defaultValues lives in lingui.config.ts, which translators never see, and nothing carries it into the TMS - Crowdin or Translation.io have no idea __appName exists. Going the other way, a translator can't request a variable either; they'd have to guess a name, and a wrong guess renders empty in production with no build-time error and no runtime warning. The RFC lists this as a caveat ("by convention only"), but I think it's the core of the design rather than a footnote.

That's worth contrasting with #2517, where a term is an actual catalog message. The translator opens the editor, sees the variants, and knows what's available - discovery is free because the mechanism is the catalog itself.

I'd also separate gender out. In most sentences the gender that matters belongs to the referent, not to a global user attribute - as soon as it's {item} or {friend}, a single __gender doesn't help. That is what #2517 targets.

[Goodwine]

To clarify, this proposal isn't about specific terms, which shifts the burden onto the app developer to consider them, which isn't wrong, but as I stated earlier, even with the best intentions, they can't be expected to know dozens or hundreds of languages and their grammar rules.

Furthermore, this proposal specifically does not concern itself with the referent of a sentence (which #2517 appears to address), focusing instead on the end user's experience reading the app, as the Android's documentation suggests.

For transparency, our process involves ingesting .po files into a system used by our translators, who do not write ICU themselves. When they identify a message addressed at the end user that can be gendered according to the user's preferences, they store those as separate variants for each gender.

We then transform those translations from that system back into .po format. While we previously generated output similar to Android’s one-bundle-per-locale-per-gender model, the current plan is to merge these variants into ICU-select expressions using a pre-defined (and configurable, but stable) placeholder variable such as __gender, given that only a minimal fraction of messages actually require such variations.

So, while the implementation itself would be "by convention", I don't think it's impossible to build around it. But I do understand that without a systematic way to build these (as we're planning to do for our use case), or to enforce it.

[timofei-iatsenko]

This proposal is totally makes sense to me. It also very easy to implement. The concern about discoverability of the available variables is totally correct - but it's not a blocker. If in your team, or in your AI docs you have this stated that you always have gender or other vars available, it's totaly fine.

However i would steer the implementation in slightly diffrent direction. This variables is runtime-related things. Where the lingui.config is about cli configuration and compile time things.

This default variables should be simply specified during creation of i18n object and it should be a way to extend/override it during app lifiteme.

Say for example - we don't have a user info right after application startup, so we don't know a gender. We create an i18n object without this data, then when user data is coming you just:

i18n.setVariables({
  gender: user.gender
})

So here are usecases i see:

1. Should be a way to initialize i18n object with a set of default variables
2. Should be a way to add/remove/modify variables
3. Should be a way to set variable as computed property (i think just setting a getter could be enough)
4. New variables should notify the subscribers and cause a re-render on set (of course changes in a getter would not cause a re-render because it's impossible to track them)

So to adress (1), we just need to extend a

export type I18nProps = {
  locale?: Locale
  locales?: Locales
  messages?: AllMessages
  missing?: MissingHandler
}

With a new property. (name is TBD)

To address (2) and (3) something as i18n.setVariables() should be good. But need to decide, how to change one property without accessing others, smth like this:

// i want to override only gender, and keep rest
i18n.setVariables((prev) => {
  ...prev
  gender: user.gender
})

// i want to reset all to just this
i18n.setVariables({
  gender: user.gender
})

// computed property
i18n.setVariables({
  get gender() { return user.gender }
})

To address (4) setVariables just need to emit into underlying event emitter.

[Goodwine]

Hello, and thank you for your comments. I like your proposal of a different API for the proposed feature. I think it's clever to make it part of the i18n instance, as this allows it to serve different needs.

Althought I was looking at the problem space from the configuration angle because I'm looking a this problem through the lenses of a platform developer rather than an application developer (i.e. it's easier to ask App devs to drop-in a config file rather than it is to ask them to inject special logic into their apps), I like that the API/surface area for implementing the desired use case is minimally intrusive, and best of all, explicit.

I'd be happy if that is the desired supported approach

[timofei-iatsenko]

It will not be possible from the configuration file. Configuration file is not injected in runtime and it has nodejs dependencies.

Also from a perspective a platform developer it wouldn't be possible to create a 1 config for all apps, because the way how user or other global variables you want to pass are initilized could be diffrent and exists on a diffrent stages of the app lifecycle from app to app.

[Goodwine]

Fair points, I will prepare a proof of concept PR implementing your suggestion.

This is kind of my first RFC on github, so I'm not quite sure whether I need to update the original post or not :)

[Goodwine]

i18n.setVariables({
  gender: user.gender
})

Regarding this API. I kinda like it, but should there perhaps be a singular variant to only set one without clobeering the rest?

[Goodwine]

I implemented a PR following your suggestion - #2661

I like how it works, and it makes sense to make this part of the i18n instance/setup rather than something configured globally