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.

Auto-detection needs at least two forms. When you apply the formatter by name, a language without plural forms, such as Japanese, accepts one form. Otherwise, the number of forms must match what the selected rule expects, for example two to four for English; a mismatch raises a formatting error.

You can also pass an IEnumerable<object>, such as a string[]: 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" });

The formatter doesn’t accept a string, even one such as "5", or a collection of value types, such as int[]: a named call throws a FormattingException, and auto-detection leaves the value to the next formatter.

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