RFC: Grammatical Case Translations in Lingui

[andrii-bodnar]

Let translators render nouns in the correct grammatical form for their language, without asking developers to know or care about those forms. A source message references a noun once; each locale decides how to decline it.

Problem

In English a noun keeps the same shape wherever it appears - "I see a sword", "I hit with a sword". In many other languages the noun itself changes depending on its role in the sentence.

In Estonian, "sword" is mõõk as a subject, mõõka as a direct object, mõõgaga when used as an instrument - fourteen forms in total. Finnish has fifteen. Polish, Czech, or Ukrainian have six or seven. German has four, plus article changes. Translators working into these languages need a way to pick the right form for each spot in a sentence.

Lingui doesn't give them one. When a developer writes

t`${player} hit a ${enemy} with a ${item}`

the extracted message is {player} hit a {enemy} with a {item}, and the translator receives enemy and item as opaque placeholders - already in one fixed form, with no way to ask for "enemy as a direct object" or "item as an instrument". select doesn't help either: it lets the developer branch on a value, but for declension only the translator knows which form a noun needs in their sentence.

In practice, users either precompute every case variant at the call site (which blows up combinatorially), write a different source sentence for every noun/case pair, or accept phrasings that read awkwardly in the target language. This is a long-standing gap for anyone translating into Slavic, Baltic, or Finno-Ugric languages.

Proposal

1. The term macro

A term is a noun/phrase that needs multiple grammatical forms:

import { term } from "@lingui/core/macro"

export const creeper = term("creeper")
export const sword   = term("sword")
export const apple   = term("apple", { id: "term.apple", comment: "Inventory item" })

Compiles to a MessageDescriptor using ICU select on a _case placeholder:

export const creeper = /*i18n*/ {
  id: "auto-id-creeper",
  message: "{_case, select, other {creeper}}",
}

The babel plugin reuses the existing descriptor/select machinery, so extraction, id hashing, and comments work the same as for msg. Users never type _case or select by hand.

2. Usage

import { t } from "@lingui/core/macro"
import { creeper, sword } from "./terms"

function HitLog({ player }) {
  return t`${player} hit a ${creeper} with a ${sword}`
}

Extracted source: {player} hit a {creeper} with a {sword}.

3. Custom formatter registry

I18n gains a small registry; interpolate() falls back to it when a token's type isn't a built-in:

type CustomFormatter = (value: unknown, format: string) => string

class I18n {
  private _customFormatters = new Map<string, CustomFormatter>()
  registerFormatter(name: string, formatter: CustomFormatter) {
    this._customFormatters.set(name, formatter); return this
  }
}

// in interpolate()
const formatter = (formatters as any)[type] ?? customFormatters?.get(type)

Unknown types still gracefully produce the raw value, preserving current behavior.

4. Built-in declension formatter

Registered by I18n itself, in the constructor. It resolves a term descriptor with _case bound to the requested case name:

this._customFormatters.set("declension", (value, caseForm) => {
  if (value && typeof value === "object" && "id" in value) {
    return this._((value as { id: string }).id, { _case: caseForm })
  }
  return String(value ?? "")
})

5. Translator view

One message per term, plus {placeholder, declension, caseName} in sentences. Each locale declares whichever cases it needs.

Term creeper:

• English: {_case, select, other {creeper}}
• Estonian: {_case, select, nom {kreeper} gen {kreeperi} par {kreeperit} com {kreeperiga} other {kreeper}}
• German: {_case, select, nom {ein Creeper} acc {einen Creeper} dat {einem Creeper} gen {eines Creepers} other {Creeper}}

Sentences:

• English: {player} hit a {enemy, declension, other} with a {item, declension, other}
• Estonian: {player} lõi {enemy, declension, par} {item, declension, com}
• German: {player} hat {enemy, declension, acc} mit {item, declension, dat} getroffen
• Finnish: {player} löi {enemy, declension, par} {item, declension, ade}

Resolving Estonian with { player: "Steve", creeper, sword } yields: Steve lõi kreeperit mõõgaga.

Why this shape

• One message ID per term - no N case-specific IDs to manage.
• Each locale owns its own case set - source language stays case-agnostic.
• Plain ICU select - standard syntax parsed by Crowdin, Phrase, Lokalise, etc.
• Small surface area - one new public API (registerFormatter), one new macro (term); existing messages unchanged.
• The developer does not need to worry about how many cases there are in each target language.

Caveats

• select repurposed for cases. Case keys (gen, par, …) are a convention, unvalidated by ICU or the parser. A typo in {enemy, declension, pra} silently falls through to other. Likely mitigation: lingui compile lint for unknown keys per locale.
• Extra runtime work per placeholder. Each {x, declension, case} triggers a nested i18n._(). Negligible individually, non-zero in loops.
• TMS UX gap. Unlike plural (fixed CLDR categories), case keys have no authoritative list. Translators need to know their own language's keys; we'd likely publish a recommended per-locale set in docs.

Open questions

• How to support external messages, e.g. usernames, to make them translatable and "declinable" in cases such as Hello, {userName}!?

[andrii-bodnar]

Additional context: https://github.com/unicode-org/inflection - Unicode's approach to solving language inflection programmatically (on early stage, limited number of languages)

[timofei-iatsenko]

I read it quickly, could not say that i understood the problem for 100%, but it make me think that a feature which potentially also could solve the problem described in this task was at the back of my mind for quite some time.

Given:

export const TAKE_A_BREAK_TITLES: Record<
  AddTakeABreakRequest['type'],
  MessageDescriptor
> = {
  H24: msg`1 day`,
  H48: msg`2 days`,
  D3: msg`3 days`,
  D7: msg`7 days`,
  D14: msg`14 days`,
  D30: msg`30 days`,
  D90: msg`90 days`,
  TEST_5_MIN: msg`5 minutes (Test)`,
  TEST_1_MIN: msg`1 minute (Test)`,
}

 const jsx = <Trans>
  You understand you are about to set a Take a Break for{' '}
    {ph({
      period: t(TAKE_A_BREAK_TITLES[type]),
    })}
  . Once set, you will be logged out.
</Trans>

Will generate You understand you are about to set a Take a Break for {period}. Once set, you will be logged out. and bunch of separate 1 day 2 days etc.

Sometimes, the content of a placeholder ({period}) does not align perfectly with the outer message, as described in this issue. And since it's a distinct elements in the catalog where the content could be resused in a diffrent place a translator has no flexibility to fix this.

One of the options could be just inline the whole map into the host message like so:

const jsx = <Trans>
  You understand you are about to set a Take a Break for
    <Select value={type} H24="1 day" H48="2 days" />. Once set, you will be logged out.
</Trans>

So produced message would be:
You understand you are about to set a Take a Break for {type, select, H24 {1 day} H48 {2 days} }. Once set, you will be logged out.

Which is giving a perfect flexibility for translator to change the outer and placheolder content.

However this is very unconvinient to use, if you need to reuse this map in more than one place. You had to copy-paste and then deal with the fact that in need to change this in every place and it may go out of sync.

So the my idea was to implement a Static Analysis which would inline expressions if possible.

// pseudocode
const  TAKE_A_BREAK_TITLES = <Select value={type} H24="1 day" H48="2 days" />;

const jsx = <Trans>
  You understand you are about to set a Take a Break for
    {TAKE_A_BREAK_TITLES}. Once set, you will be logged out.
</Trans>

Macro and extractor automatically resolves TAKE_A_BREAK_TITLES to it's content and inline into a message.

The problem is that approach is that transformer, which is usually opperates on a single file, need to read and analyze other files as well to resolve refrences from separate modules. And that could be a massive bottleneck in performance. However with a modern rust based tooling it could be less noticable.

I think that feature i descrbed might partially or even fully solve the problem from this discussion. WDYT?

[andrii-bodnar]

Sometimes, the content of a placeholder ({period}) does not align perfectly with the outer message, as described in this issue. And since it's a distinct elements in the catalog where the content could be resused in a diffrent place a translator has no flexibility to fix this.

Yes, this applies to the problem I described. The main issue is that the number of cases in the translation depends on the language and the outer text. Translators need the flexibility to choose which placeholder form to use (nominative, accusative, genitive, or dative) for a specific outer message.

I will adjust my example to your approach. Imagine we have a message:

export const MINECRAFT_ITEM_TITLES: Record<
  PickupItemRequest['type'],
  MessageDescriptor> = {
  DIAMOND_AXE: msg`Diamond Axe`,
  NETHERITE_SWORD: msg`Netherite Sword`,
  IRON_PICKAXE: msg`Iron Pickaxe`,
  GOLDEN_APPLE: msg`Golden Apple`,
  DIRT_BLOCK: msg`Block of Dirt`,
}

const jsx = (
  <Trans>
    Steve picked up the{' '}
    {ph({
      item: t(MINECRAFT_ITEM_TITLES[type]),
    })}
    .
  </Trans>
);

Result:

Steve picked up the {type, select, 
  DIAMOND_AXE {Diamond Axe} 
  NETHERITE_SWORD {Netherite Sword} 
  IRON_PICKAXE {Iron Pickaxe} 
  GOLDEN_APPLE {Golden Apple} 
  DIRT_BLOCK {Block of Dirt} 
  other {item}
}.

In this case, the translator is free to choose the right form of the placeholder and it will be aligned with the outer message.

Then, for example, Estonian translation:

Steve võttis üles {type, select, 
  DIAMOND_AXE {teemantkirve} 
  NETHERITE_SWORD {netheriitmõõga} 
  IRON_PICKAXE {raudkirka} 
  GOLDEN_APPLE {kuldõuna} 
  DIRT_BLOCK {mullaploki} 
  other {eseme}
}.

This table shows how the "Base" name (what you’d see in a menu, for example) transforms when Steve actually interacts with it in a sentence:

Item Key	English Name	Base Form (Nominative)	In-Sentence (Genitive)	What Changed?
DIAMOND_AXE	Diamond Axe	teemantkirves	teemantkirve	The final -s is dropped.
NETHERITE_SWORD	Netherite Sword	netheriitmõõk	netheriitmõõga	The -k softens into a -ga.
IRON_PICKAXE	Iron Pickaxe	raudkirkas	raudkirka	The final -s is dropped.
GOLDEN_APPLE	Golden Apple	kuldõun	kuldõuna	An -a is added to the end.
DIRT_BLOCK	Block of Dirt	mullaplokk	mullaploki	The double -kk weakens to a single -k-.

It looks like your suggested approach might work. The only issue is the number of items that will be baked into each sentence where a placeholder is used. It would be much more convenient if each item were translated separately (including each declension form) and then reused. In the specific context, the translator would only need to specify which form they want to use.

[timofei-iatsenko]

I re-read an RFC, it seems i understand it now. I like the idea, the following question come to my mind:

How translator looking at this message only {player} hit a {creeper} with a {sword} would know that creeper and sword marked by developer with term and they able to use a {enemy, declension, form} formatter?

I think another macro should be implemented, to consume terms:

const creeper = term("creeper") // produce a DeclensionTerm type
const sword   = term("sword")

// DeclensionTerm is not directly assignable to string, so you could not just interpolate it directly, you need to use a `declension` macro 
t`${player} hit a ${declension(creeper)} with a ${declension(sword)}`

This would generate:

{player} hit a {enemy, declension, other} with a {item, declension, other}

Now translator see that this term has a declension forms and could choose one.

[andrii-bodnar]

Yes, this should be more clear for translators.