# Plural formatter

> Choose a word form based on a count, following the pluralization rules of the active culture.

Choose a word form based on a count, following the pluralization rules of the active culture.

Languages handle plurals differently: English has two forms ("hour" and "hours"), some languages have one, and others have several. The Plural formatter picks the right form by following the Unicode [Common Locale Data Repository](https://cldr.unicode.org/) (CLDR) [plural rules](https://cldr.unicode.org/index/cldr-spec/plural-rules). Apply it explicitly with the name `plural`, or omit the name to apply it implicitly to a number or a collection.

{ /*  Mermaid source kept for the future doc platform; shown as the static image below until mermaid rendering is supported.  */ }

```mermaid
flowchart TD
    full["{value:plural:zero|one|two|few|many|other}"]

    full --> p1["value"]
    full --> p2["plural"]
    full --> p3["zero|one|two|few|many|other"]

    p1 --> d1["Any number"]
    p2 --> d2["Formatter name: plural<br/>(or implicit)"]
    p3 --> d3["Plural arguments,<br/>smallest to highest"]

    classDef code   fill:#F5F5F5,stroke:#BDBDBD,color:#111;
    classDef orange fill:none,stroke:none,color:#F37021;
    classDef green  fill:none,stroke:none,color:#67BC6B;
    classDef purple fill:none,stroke:none,color:#765BA7;

    class full code;
    class p1,d1 orange;
    class p2,d2 green;
    class p3,d3 purple;

    linkStyle default stroke:#2196F3,stroke-width:1.5px;
```


**Anatomy of the plural formatter syntax.:**
![](/api/media?file=/engine/6000.7/media/images/smart-strings-plural-formatter.svg)

CLDR defines these plural categories: `zero`, `one`, `two`, `few`, `many`, and `other`. Provide one format per form the culture uses, in CLDR order. The formatter supports cardinal rules.

The formatter determines which rules to apply from the active culture: the [CultureInfo](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo) passed to [`Smart.Format`](/engine/6000.7/script-reference/unity/smartstrings/smart/format.md), or `CultureInfo.CurrentUICulture` when none is given. Override the culture with the options in parentheses, for example `(en)` to force English plural rules.

```cs
// "I have 10 apples"
            Smart.Format(new CultureInfo("en"), "I have {0:plural:an apple|{} apples}", 10);

            // "1 банан"
            Smart.Format(new CultureInfo("ru"), "{0} {0:plural:банан|{} банана|{} бананов}", 1);
```

An empty placeholder `{}` reuses the current value, so you can repeat the count inside a form.

The formatter requires at least two forms when applied explicitly. The number of forms you provide must match what the selected rule expects; a mismatch raises a formatting error.

| Smart String                            | Argument       | Result           |
| --------------------------------------- | -------------- | ---------------- |
| `I have {0:plural:an apple\|{} apples}` | `1` (English)  | I have an apple  |
| `I have {0:plural:an apple\|{} apples}` | `10` (English) | I have 10 apples |
| `{0:plural(en):{} apple\|{} apples}`    | `2`            | 2 apples         |

You can also pass an `IEnumerable`: the formatter uses its item count as the plural value. This lets one argument drive both a plural and a list:

```cs
// "The following people are impressed: bob, and alice."
            Smart.Format("The following {0:plural:person is|people are} impressed: {0:list:{}|, |, and}.", new[] { "bob", "alice" });
```

## Custom plural rules

Provide a [`CustomPluralRuleProvider`](/engine/6000.7/script-reference/unity/smartstrings/extensions/custompluralruleprovider.md) as the format provider to replace the rules for a single call without changing the defaults elsewhere. This is useful when a scenario needs fewer or different forms than the culture's standard rules.

## Additional resources

* [List formatter](/engine/6000.7/manual/scripting/smart-strings/formatters/list-formatter.md)
* [Conditional formatter](/engine/6000.7/manual/scripting/smart-strings/formatters/conditional-formatter.md)
* [Smart Strings](/engine/6000.7/manual/scripting/smart-strings.md)