Skip to content

Messages & plurals

Format ICU MessageFormat strings — placeholders, numbers, and especially pluralisation and gender/word selection — without hardcoding any language's grammar rules. A single pattern adapts: English needs one/other, Arabic needs six categories, and Message() picks the right branch from CLDR for you.

The pattern language

A pattern is plain text with {…} placeholders. There are four placeholder shapes:

Shape Example Renders
Simple Hello, {name}! substitutes the argument as-is
Number {n, number} · {n, number, integer} · {n, number, percent} locale-formatted number
Plural {n, plural, one {# item} other {# items}} picks a branch by plural category; # is the value
Select {g, select, female {her} male {his} other {their}} picks a branch by exact string match

Inside a plural/selectordinal branch, # is replaced by the (locale-formatted) number. Two refinements:

  • Exact matches — =0 {none} one {# item} other {# items} uses the =0 branch when the value is exactly 0, before falling back to the category.
  • offset:n — {n, plural, offset:1 =0 {nobody} one {you and # other} other {you and # others}} subtracts n from # (for "you and 2 others" style phrasing).

An other branch is required in every plural/selectordinal/select — it's the fallback when no category matches. Escape a literal brace or # by wrapping it in single quotes: '{', '#', and '' for a literal apostrophe.

Messages

var c = new Cosmo("en");
c.Message("{count, plural, one {# file} other {# files}}",
          new Dictionary<string, object?> { ["count"] = 3 });
// "3 files"
c.Message("{n, number} of {m, number}",
          new Dictionary<string, object?> { ["n"] = 4560, ["m"] = 0.2 });
// "4,560 of 0.2"
// Positional (params array):
c.Message("{0, plural, one {# file} other {# files}}", 3);
// "3 files"

Named vs positional arguments

Pass positional arguments through params object?[] ({0}), or named arguments in a Dictionary<string, object?> ({name}). The parser uses ICU plural rules and number formatting, with support for number, date, time, and spellout arguments.

Ordinals in messages

selectordinal works like plural but uses ordinal categories — the "1st / 2nd / 3rd" wording rules:

var c = new Cosmo("en");
string p = "{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} place";
c.Message(p, new Dictionary<string, object?> { ["n"] = 1 });  // "1st place"
c.Message(p, new Dictionary<string, object?> { ["n"] = 22 }); // "22nd place"

For ordinal text such as "22nd" without writing branches, use Ordinal().

Plural category

Sometimes you want the raw decision rather than a formatted message — e.g. to pick an image or a CSS class. PluralCategory() returns the LDML category a number falls into for the locale, the same choice Message() makes internally.

var en = new Cosmo("en");
en.PluralCategory(1);           // "one"
en.PluralCategory(2);           // "other"
en.PluralCategory(2, ordinal: true); // "two"
new Cosmo("ar").PluralCategory(0);   // "zero"

Returns one of zero, one, two, few, many, other. Pass ordinal = true for ordinal rules instead of cardinal.

Which categories does a locale use?

The set varies wildly: English has one/other (cardinal), Arabic has all six, Japanese has only other. Write every plural branch you reference, but always keep other — it covers any category you didn't spell out.

Practical examples

A notification badge sentence. One pattern handles zero, singular, and plural without branching in your code:

var c = new Cosmo("en");
string p = "{n, plural, =0 {No new messages} one {# new message} other {# new messages}}";
c.Message(p, new Dictionary<string, object?> { ["n"] = 0 }); // "No new messages"
c.Message(p, new Dictionary<string, object?> { ["n"] = 5 }); // "5 new messages"

"You and N others" with offset. The offset keeps the displayed # one less than the real count:

var c = new Cosmo("en");
string p = "{n, plural, offset:1 =1 {You liked this} one {You and # other liked this}"
         + " other {You and # others liked this}}";
c.Message(p, new Dictionary<string, object?> { ["n"] = 1 }); // "You liked this"
c.Message(p, new Dictionary<string, object?> { ["n"] = 3 }); // "You and 2 others liked this"