Plural formatter

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 (CLDR) plural rules. Apply it explicitly with the name plural, or omit the name to apply it implicitly to a number or a collection.

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;

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 passed to Smart.Format, or CultureInfo.CurrentUICulture when none is given. Override the culture with the options in parentheses, for example (en) to force English plural rules.

// "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.

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:

// "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 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
• Conditional formatter
• Smart Strings