Reference
Formatting data for a document that crosses a border
A document can render a writing system perfectly and still state the wrong date. These pages are about the values: whether the number, the date, the name and the address are written in a form the reader will read the way you meant.
The other half is writing systems, which is about rendering: whether the glyphs come out shaped, joined and in the right order. And the layout each of these values lands in is parts of a document. Every page here links across to the block its value belongs in.
Where this API sits: nowhere, and that is worth saying plainly. It renders HTML to PDF, so by the time markup reaches it every value is already a string your code produced. There is no locale option because there would be nothing for one to do. What a document adds to the general internationalisation problem is the second half of every page below: what the formatting decision does to the layout, because a separator changes a column width and a translated header changes the pagination of everything after it.
One thing you will not find here: a specific country's tax identifier format, a specific language's plural rules, or a percentage by which translated text expands. Those are real, variable, and maintained properly elsewhere. Taking them from a data source and measuring your own strings is the honest instruction, and quoting a number would be worse than useless.
Numbers and money
A number in a document is a claim about an amount. Every one of these pages is a way that claim can be read as a different amount than the one you meant, by a reader doing nothing wrong.
- Decimal and thousands separators
The comma and the point swap roles between conventions, so the same string of characters is two amounts a thousand apart depending on who is reading it.
- Currency symbol placement
The symbol goes before the amount in some conventions and after it in others, with different spacing, and the choice affects both meaning and column alignment.
- Negative amounts
A negative figure written with a leading minus, with parentheses, or with a trailing sign, where the conventions differ and one of them is easy to miss entirely.
- Rounding and the half unit
Which way a value exactly halfway between two representable amounts is rounded, and at which point in the calculation the rounding happens.
Dates and times
A date or a time is only unambiguous if it carries enough information to be unambiguous. Most of the formats in common use do not, and the failure is silent because both readings look like a valid date.
- Ambiguous numeric dates
An all-numeric date whose day and month can be swapped without producing anything that looks wrong, which makes it unreadable rather than merely unclear.
- Time zones on timestamps
A time printed in a document without saying which zone it is in, which is unresolvable by the reader and frequently wrong by a day at the boundaries.
Names, addresses and identifiers
Names, addresses and identifiers are the fields where a system's assumptions about the world are written down, and where they are wrong for somebody.
- Address format by country
Which lines an address has and what order they go in, both of which vary by destination and neither of which is a property of your database schema.
- Personal name order
The assumption that a person has a given name followed by a family name, in that order, which is wrong often enough that a document built on it insults people regularly.
- Phone number formatting
A number printed in a national format, which cannot be dialled from outside the country it belongs to and gives the reader no way to work out what is missing.
- Tax identifier formats
Registration numbers whose length, character set and check rules differ by country, printed and validated by systems that assume the shape of the first country they supported.
Language in generated text
Text assembled by a program rather than written by a person. It is where the grammar of the output depends on data, and where a template that works in one language is ungrammatical in another.
- Pluralisation in generated text
Text assembled around a number, where the grammar depends on the number and the template usually assumes there are exactly two possibilities.
- Label expansion when translated
The same label in another language is frequently longer, and a layout tuned to the original wraps, clips or reflows once the translation goes in.
- Amounts inside right-to-left text
A left-to-right run such as an amount, a reference or a URL embedded in right-to-left text, where the boundary between the two is resolved by an algorithm and not always the way you meant.
- Units and measurements
A measured quantity printed without its unit, in the wrong system for the reader, or separated from its unit by a line break.
- Sort order and collation
The order a list is sorted into, which is defined by the language rather than by the byte values of the characters.