Plurals in generated line text, and 1 items

The defect

The visible version is the classic: a line reading 1 items, because the template appended an s. The fix people reach for, a conditional on whether the count is one, is correct for English and wrong as a general rule, because languages differ in how many plural categories they have and in which numbers fall into which category. A template with two branches cannot express a language with more, so a document translated into one comes out ungrammatical in a way that no amount of translation review catches, because the translator was given two strings and there was no third to translate.

What it does to the document

Generated descriptions are the least predictable text in a document because their length depends on data. A line description assembled from parts can be twice as long in one language as another, which is what turns a one-line table row into a two-line row and changes how many rows fit on a page.

The decisions

Reasons rather than a description of the code. Formatting rules are data that changes, so most of these are about taking the rule from a maintained source rather than encoding today's answer.

• Use a plural-rules facility that takes a locale and returns a category, rather than an is-it-one conditional.
• Give the translator one message per category the target language has, not two, and let the tooling determine how many that is.
• Never build a sentence by concatenating fragments around a number. Word order differs, and a fragment that is a prefix in one language is a suffix in another.
• Include the number in the message rather than gluing it on, so its position within the sentence is the translator's decision.
• Watch for zero. Some languages treat it as its own category, and in most documents a zero case reads better as a sentence than as a count anyway.
• Remember this applies to generated descriptions and notes, not just to counts. Anything a program assembles from parts has this problem.

In code

The formatting happens before the markup exists, so this is mostly code rather than CSS. The wrong version is kept in a comment where the wrong version is the thing people write.

// Ask the locale how many categories it has, rather than assuming two.
const count = 1;
const rules = new Intl.PluralRules("en-GB");
rules.select(count);              // "one"
new Intl.PluralRules("ar").select(count);   // a different set of categories

// One message per category the target language actually has. The number
// goes inside the message, so its position is the translator's choice.
const messages = {
  one: "{n} item on this order",
  other: "{n} items on this order",
};
const text = messages[rules.select(count)].replace("{n}", String(count));

/* Not this: two branches, and a number glued to a fragment.
   const bad = count + " item" + (count === 1 ? "" : "s");             */

What people do instead

Solving it with a ternary on whether the count is one. It fixes the visible English defect and hard-codes the assumption that two forms are enough, which is the thing that later has to be undone everywhere rather than in one place.

How to find out rather than assume

Render the document with counts of zero, one, two and a large number, in every language it is issued in. Then have a native speaker read the generated lines, because this is the class of defect that only a speaker of the language will see.

Where the API sits in this

Nowhere, and that is worth saying plainly. This API renders HTML to PDF. By the time markup reaches it, every value in it is already a string that somebody's code produced, so there is no locale option on the render because there would be nothing for one to do. What the render controls is the page: the size, the margins, and whether the formatted value still fits the column it landed in. That is why each of these pages has a paragraph about the layout consequence, because that is the half a document adds to the general problem.

Frequently asked

Related formatting topics

The defects that travel together, then the rest of the same group.