{"canonical_url":"https://engineer.company/glossary/internationalization/","content_markdown":"# Internationalization\n\n## What it is\n\nInternationalization is the engineering that lets one product work in many\nlanguages and regions without its code being changed for each of them. The W3C\ndefines it as designing and building a product, an application or a document so\nthat localizing it later is easy, whatever the culture, region or language of\nthe audience. The word is also spelled internationalisation, and it is shortened\nto i18n, because 18 letters stand between its first i and its last n. Some\npeople call the same idea globalization.\n\nThe W3C puts the division of labour in one sentence: the people who design and\nbuild products internationalize them \"so that they can be easily localized by\ntranslators and localizers.\" Internationalization is done once, in the code and\nthe templates. Localization is done again for every market, in data that the\ncode reads. A product can be fully internationalized and still ship in a single\nlanguage.\n\nThe unit both of them work with is the locale. CLDR's specification defines a\nlocale as an identifier for the preferences that users across large parts of the\nworld tend to have in common: a language, often narrowed by a region, so that\n`en-GB` and `en-US` share a language and differ in how they write a date. The\nidentifier selects a translation and a set of conventions at the same time.\n\nThe W3C lists four kinds of work under the heading. The first removes barriers:\nthe product handles text as Unicode, or treats an older character encoding\ndeliberately where it must; it does not build sentences by joining fragments;\nand its code never depends on the wording shown to the user. The second adds\nsupport that only a later language will use, such as markup for text that mixes\nright-to-left and left-to-right scripts, a way to declare which language a\npassage is in, and style rules for vertical text. The third lets the code use\nlocal conventions, usually from existing libraries rather than from tables the\nteam writes itself: date and time formats, calendars, number formats and numeral\nsystems, the order in which lists sort, and the conventions for writing people's\nnames and for addressing them. The fourth keeps everything translatable out of\nthe source code, so that the right version can be loaded for each reader.\n\n## Why it matters\n\nThe W3C's argument is about timing. Reworking a product built around one\nlanguage and one culture for a global market takes far more effort and far more\ntime than designing it for the whole world from the start, and the W3C compares\nthe work to the Y2K effort to undo two-digit year fields that assumed every year\nbegan with 19. Done late, internationalization tends to mean awkward and\nexpensive re-engineering. Done early, it is a handful of habits that cost little\non the day they are adopted.\n\nThe cost of a missing habit grows with every language. A sentence assembled in\ncode from three fragments is one defect in an English product and five defects\nin a product with five locales, and in each of them the fix is not a better\ntranslation but a change to the code, reviewed and released like any other. The\nsame holds for a date formatted by hand, a list sorted by comparing bytes, or a\nlabel that a test finds by its English text.\n\nThe habits pay even when nothing is ever translated, a point the W3C makes\nexplicitly. A product sold only in English still receives names written with\nletters English does not use, addresses laid out the way another country lays\nthem out, and dates from systems that write the day before the month. Text that\nis stored as Unicode, and data that keeps a date as a date until the moment it\nis shown, handle all of that without a special case.\n\n## What it looks like in practice\n\nThe quickest test of whether a product is internationalized is a sentence with\na number in it. The version that is not builds the sentence in code:\n\n```js\nconst label = count + (count === 1 ? \" day\" : \" days\");\n```\n\nThat is correct in English and cannot be translated. Ukrainian needs three forms\nfor whole numbers and a fourth for fractions: день after 1, 21 and 101, дні\nafter 2, 3, 4 and 22, днів after 0, 5 to 20 and 25, and дня after a fraction.\nWhatever single word a translator puts in the second branch, it is wrong for\nmost numbers, because 21 takes the same form as 1 and 2 takes a different form\nfrom 5.\n\nInternationalized, the sentence becomes a key, and each language's table\nsupplies every form the language needs. In Hugo, translation tables live in the\n`i18n` directory, one file per language, named by its language tag:\n\n```toml\n# i18n/en.toml\n[days]\none = '{{ . }} day'\nother = '{{ . }} days'\n```\n\n```toml\n# i18n/uk.toml\n[days]\none = '{{ . }} день'\nfew = '{{ . }} дні'\nmany = '{{ . }} днів'\nother = '{{ . }} дня'\n```\n\nThe template asks for the key and passes the number. It contains no word of\neither language and no rule about plurals:\n\n```text\n{{ T \"days\" 21 }}\n```\n\nThe English pages render `21 days` and the Ukrainian pages `21 день`; with 2\nthey render `2 days` and `2 дні`, and with 5, `5 days` and `5 днів`. The names\n`one`, `few`, `many` and `other` are not Hugo's invention. They are the plural\ncategories defined by CLDR, the Unicode Consortium's collection of locale data,\nand Hugo's documentation points to CLDR's plural rules chart for the categories\neach language has. A new language arrives as a new file, with no change to a\ntemplate.\n\nAt scale the tables become the largest body of text in the product, and they\nneed the same discipline as code. One of this site's projects,\n[an English and Danish internationalization system](/portfolio/built-an-english-danish-i18n-system/),\ncarries 12,027 messages per locale in 458 namespace files. Each file is held to\na budget of 400 lines, a linter compares the keys across the two locales so that\nno message is present in one and missing in the other, and the Danish side\nfollows a locked vocabulary, down to the informal \"du\", that the tooling\nenforces on every commit. The page credits the budget with keeping the work\nmaintainable: without a limit per file, it says, the 458 files would have been\ntwelve.\n\n## Where it goes wrong\n\n**Sentences are glued together.** A message built as `\"Delete \" + n + \" files?\"`\nreaches the translator as two fragments with no sentence around them, in an\norder that only English needs. Another language may want the number at the end,\nor a verb form that depends on the noun. The W3C names care over the\nconcatenation of strings as part of the work. Make every sentence one message\nwith named placeholders, which a translator can move; Hugo's documentation shows\n`{{ T \"age\" (dict \"name\" \"Will\" \"count\" 1) }}` filling both a name and a count\ninside one translated sentence.\n\n**The code reads the words on the screen.** A test that finds a button by its\nlabel \"Save\", or a branch that compares a status with the text \"Paid\", works\nuntil the first translation and then fails without an error. The W3C lists\navoiding any dependence in code on user-interface strings among the first\nthings internationalization means. Compare keys, identifiers and enumerated\nvalues, and give tests a stable attribute to find an element by.\n\n**One plural rule for every language.** `count === 1` is the English rule\nwritten as code, and it is wrong for most of the languages a product may add.\nCLDR's specification defines six plural categories, zero, one, two, few, many\nand other, of which only other is mandatory, and gives each language its own\nrules for choosing among them: English uses two, Ukrainian four. Pass the number\nto the message and let the translation table carry every category the language\nuses.\n\n**A missing translation fails without a sound.** Hugo's `T` falls back to the\ndefault language when a key is missing in the current one, and returns an empty\nstring when the default has none either, so a page can ship with a gap or an\nEnglish phrase in the middle of a Danish one. Build with `--printI18nWarnings`\nto list every missing and fallback translation, turn on\n`enableMissingTranslationPlaceholders` in a preview environment so that gaps\nshow on the page, and compare the keys of every locale in continuous\nintegration.\n\n**Dates and numbers are formatted by hand.** A template that writes\n`MM/DD/YYYY`, or a number with a comma every three digits, has hard-coded one\ncountry. The same day is `10/27/26` in American English, `27/10/2026` in British\nEnglish, `27.10.2026` in Danish and `2026-10-27` in Swedish; 12,027.5 is written\n`12.027,5` in Danish, and in Norwegian, Swedish and Ukrainian with a space as\nthe thousands separator and a comma before the decimals. CLDR's specification\nrecommends storing and exchanging language-neutral data and formatting it for\nthe reader. Keep dates and amounts as plain values until the last step, and\nformat them there with the locale-aware functions the platform provides. In\nHugo, `time.Format \":date_full\"` renders one date as `Wednesday, November 3,\n2021` on an English page and `Mittwoch, 3. November 2021` on a German one.\n\n**Text is not stored as Unicode.** A product that writes \"blåbærsyltetøj\" in\nUTF-8 and reads it back as Windows-1252 shows \"blÃ¥bÃ¦rsyltetÃ¸j\", and one that\nstores text in an older single-language encoding cannot hold a Ukrainian name at\nall. Enabling Unicode is the first item on the W3C's list. Use one Unicode\nencoding, normally UTF-8, from the database to the browser, and declare it at\nevery boundary where bytes become text.\n\n## Further reading\n\n- [Localization vs. Internationalization](https://www.w3.org/International/questions/qa-i18n#i18n)\n  — the W3C's working definitions of both terms, the four kinds of work\n  internationalization involves, and why it belongs at the start.\n- [Hugo: Multilingual mode](https://gohugo.io/content-management/multilingual/)\n  — translation tables, localized dates and currencies, and how Hugo reports a\n  missing translation.\n- [Hugo: lang.Translate](https://gohugo.io/functions/lang/translate/) — the\n  lookup order across languages, plural categories in translation tables, and\n  messages with named placeholders.\n- [UTS #35, Part 1: Core](https://www.unicode.org/reports/tr35/) — CLDR's\n  specification: locale identifiers, inheritance between locales and the advice\n  to keep data language-neutral until it is shown.\n- [UTS #35, Part 3: Numbers](https://www.unicode.org/reports/tr35/tr35-numbers.html)\n  — number symbols and patterns per locale, and the plural categories with the\n  rules for choosing among them.\n\n\u003chttps://engineer.company/glossary/internationalization/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"What internationalization covers, how messages, plural rules and formats are kept out of the code, and six ways a product fails its second language.","formats":{"gemtext":"https://engineer.company/glossary/internationalization/index.gmi","gopher":"https://engineer.company/glossary/internationalization/gophermap","html":"https://engineer.company/glossary/internationalization/","json":"https://engineer.company/glossary/internationalization/index.json","markdown":"https://engineer.company/glossary/internationalization/index.md","pdf":"https://engineer.company/glossary/internationalization/index.pdf"},"kind":"page","language":"en","title":"What is internationalization?","url":"https://engineer.company/glossary/internationalization/","version":1}