plural

plural is the Core Macro for ICU plural messages. There is also a Component Macro form of the same logic, Plural.

Use it when the main problem is choosing text from plural categories. It can be used directly to produce a translated string, or embedded inside a t`...` template literal when the plural belongs to a larger message.

For the framework-agnostic Lingui semantics, see the official plural reference.

Source

Demo.svelte Catalog

<p>
  {$plural(count, {
    one: "# item",
    other: "# items",
  })}
</p>

#: src/demos/macros/plural/Demo.svelte
msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# item} other {# items}}"

Result

Preview Transformed Svelte Compiled Catalog

2 items

<p>
  {$__l4s_translate(
  /*i18n*/
  {
    id: "Md/eZS",
    values: {
      count: count
    }
  })}
</p>

/*eslint-disable*/
import type { Messages } from "@lingui/core";
export const messages = JSON.parse(
  "{\"Md/eZS\":[[\"count\",\"plural\",{\"one\":[\"#\",\" item\"],\"other\":[\"#\",\" items\"]}]]}",
) as Messages;

Locale

EN JA

Count

Usage

Svelte

<script lang="ts">
  import { plural, t } from "lingui-for-svelte/macro";

  let count = $state(2);
</script>

<!-- Standalone: produces the plural string directly. -->
<p>
  {$plural(count, {
    one: "# item",
    other: "# items",
  })}
</p>

<!-- Embedded: plural is part of a larger translated unit. -->
<p>
  {$t`Cart: ${plural(count, {
    one: "# item",
    other: "# items",
  })}`}
</p>

In .svelte files, use $plural for reactive standalone use. When nested inside $t`...`, use plural without the $ prefix.

See Reactive Macros for the full explanation, including the plural.eager escape hatch.

Astro

---
import { plural, t } from "lingui-for-astro/macro";

const count = 2;
---

<!-- Standalone: produces the plural string directly. -->
<p>
  {
    plural(count, {
      one: "# item",
      other: "# items",
    })
  }
</p>

<!-- Embedded: plural is part of a larger translated unit. -->
<p>
  {
    t`Cart: ${plural(count, {
      one: "# item",
      other: "# items",
    })}`
  }
</p>

Official Lingui

import { plural, t } from "@lingui/core/macro";

// Standalone
const label: string = plural(count, {
  one: "# item",
  other: "# items",
});

// Embedded
const message: string = t`Cart: ${plural(count, {
  one: "# item",
  other: "# items",
})}`;

Exact value match

Use a plain numeric key to match an exact count. Exact matches take precedence over category keys.

plural(count, {
  0: "No items",
  one: "# item",
  other: "# items",
});

The component macro Plural expresses the same match with an underscore-prefixed prop (_0="No items"). The function form uses a plain number key; no underscore is needed.

When plural is a good fit

• the message depends on a numeric count
• you want official ICU plural behavior
• the function form reads naturally in the current file