Introduction to Pluralizer for .NET

Let’s say you want to output a sentence that varies slightly, depending on the number of users that are in your system.

For example, you want it to say one of these variations (a common predicament in my experience):

  • There is 1 registered person.
  • There are 398 registered people.

To achieve this, you typically have to write something ugly like this (I’m using the Razor view engine for brevity… aspx would be even worse):

There @(numUsers == 1 ? "is" : "are") @numUsers registered @(numUsers == 1 ? "person" : "people").

Ugh… So tedious. With Pluralizer, you can get the same result with this line of code:

@Pluralizer.Pluralize("There {is} {_} registered {person}.", numUsers)

What Is Pluralizer?

Definition in English: Pluralizer is a small library to make simple string formatting easier. It allows you to use one string to express two variations of a sentence that are dependent on a numeric value.

Definition in Code:

var str = "There {is} {_} {person}.";
var single = Pluralizer.Instance.Pluralize(str, 1);
Assert.AreEqual("There is 1 person.", single);

var several = Pluralizer.Instance.Pluralize(str, 47);
Assert.AreEqual("There are 47 people.", several);

Implementation

First, here is the most basic signature (note that there are a couple of overloads, but more on those next time):

public string Pluralize(string sentence, double number);

You provide the sentence (or, more accurately, the sentence template), and the number that will be used.

For the sentence (in over-simplified terms), follow these basic guidelines:

  • start by writing the sentence in its singular form.
  • wrap any words that you want “pluralized” in curly braces
  • nouns are handled automatically by the built-in PluralizationService class in Entity Framework for .NET 4
  • only the most simple verbs and pronouns are automatically handled. You’ll probably have to handle those by yourself, separated by the pipe character.
  • the number itself is displayed using the special underscore placeholder (i.e. write this to get the number itself printed: {_})
  • manually define the singular and plural words by separating them with a pipe character (e.g. {singular|plural}).

Simple Examples

The following are using a simple, static (i.e. singleton) implementation. It is possible to instantiate a pluralizer and teach it, but we’ll get into that next time. Also, for these examples to work, you’ll have to include “using Pluralize;” at the top of your file.

var str = "There {is} {_} {person}.";

var single = Pluralizer.Instance.Pluralize(str, 1);
Assert.AreEqual("There is 1 person.", single);

var plural = Pluralizer.Instance.Pluralize(str, 67);
Assert.AreEqual("There are 67 people.", plural);

A couple of very common verbs and pronouns are handled automatically; also, we won’t display the actual number this time:

var str = "{She} {is} going to the store.";

var single = Pluralizer.Instance.Pluralize(str, 1);
Assert.AreEqual("She is going to the store.", single);

var plural = Pluralizer.Instance.Pluralize(str, 5);
Assert.AreEqual("They are going to the store.", plural);

Define the singular and plural values manually by separating them with a pipe character, like this: {singular|plural}.

var str = "There {he} {goes|go}.";

var single = Pluralizer.Instance.Pluralize(str, 1);
Assert.AreEqual("There he goes.", single);

var plural = Pluralizer.Instance.Pluralize(str, 42);
Assert.AreEqual("There they go.", plural);

// A tiny step further...
str = "{She} {is} going to {her|their respective} {home}.";
var customPlural = Pluralizer.Instance.Pluralize(str, 5);
Assert.AreEqual("They are going to their respective homes.", customPlural);

That’s a basic introduction. This alone should save you time and frustration when making friendly messages in your UI. For the next post, we’ll into into some more things that you can do like define multiple numeric variables, format numbers, etc.

How to Get it

NuGet

The easiest way to get your hands on .net assemblies. The package is called “Pluralizer” and it’s up at the NuGet official package source.

PM> get-package Pluralizer -remote |fl
PM> install-package Pluralizer

Manual Download

If for some reason you enjoy pain, you can ignore NuGet and manually download and add the assembly to your project yourself.

What’s Up with the Project?

First, this is in very early stages (i.e. version 0.1). It will be open source; I’ll post the source on GitHub as soon as I get a chance.

Basically, it’s a single public class (Pluralizer) with a few overloads of the Pluralize() method (and of course, some tests to get started with).

I was reading a post on Scott Hanselman’s blog and it inspired me to take things a step further… Pluralizer was born.

Tagged with: ,
Posted in Pluralizer
  • Pingback: More Features in Pluralizer – JasonQ

  • Stuart Gardner-Vaughan

    Great library, just what I was after. Works a treat, cheers.

    Just noticed a small typo on the intro page – “@Plurtalizer.Pluralize”

    • jasonquerido

      Thanks! Fixed. Who says we rely on the compiler?! :P

  • http://bindsolution.com/ Riderman de Sousa Barbosa

    Works in other languages ​​ than English? For example in pt-br?

    • jasonquerido

      Not currently, but what a great idea! I’ll look at adding that as soon as I can find two seconds.