{"canonical_url":"https://engineer.company/glossary/localization/","content_markdown":"# Localization\n\n## What it is\n\nLocalization is the work of adapting a product to one particular market: its\nlanguage, and with it the conventions its readers expect for dates, numbers,\nprices, names, addresses and the order of a list. The W3C defines it as adapting\na product, an application or the content of a document to one target market, so\nthat it suits that market's language and culture and meets whatever else the\nmarket needs, and it calls that market a locale. The word is also spelled\nlocalisation, and it is shortened to l10n, for the 10 letters between its first\nl and its last n.\n\nThe W3C adds that localization is often thought of as a synonym for translating\nthe interface and the documentation, and that it is often a substantially more\ncomplex job. Its list of what may need adapting covers numeric, date and time\nformats; currency; keyboard layout; collation and sorting; symbols, icons and\ncolours; text and graphics that a culture may misread or find insensitive; legal\nrequirements; the formats of addresses, postal codes, phone numbers and the\norder of names; and the readability needs of each script. Where the way of doing\nbusiness differs, with accounting as the W3C's example, the adaptation may mean\nrethinking the logic, the visual design or the presentation of the product.\n\nLocalization depends on internationalization and comes after it.\nInternationalization is done once, in the code, so that nothing about a single\nmarket is built into it. Localization is done for each locale, in data the code\nreads: the translated messages, and the conventions that turn a stored date or\namount into the text a reader expects. A product that has been internationalized\nwell can gain a locale without a change to its code; one that has not must be\nchanged again for every market it enters.\n\nMost of the convention data does not have to be written by the team. The Unicode\nConsortium's CLDR project collects it for over 100 languages, checked by\nspecialists and people who speak each language natively, and its own example is\nthe list of files on a phone: the format of the dates, the numbers, the units of\nthe file sizes and the alphabetical order all vary with the language and are\nusually supplied by CLDR. The project states that its data is built into all\nmodern operating systems and browsers and into languages such as Java, C#, Swift\nand JavaScript. A product gets most of its formats from the platform, provided\nthe code asks the platform for them instead of writing them itself.\n\n## Why it matters\n\nA product that is translated but not localized reads as foreign. Every label is\nin Danish, and the date still puts the month first, the price still carries a\ndollar sign and the list of towns still files Aarhus under A. Readers notice\neach of these at once, and each one tells them the product was made for somebody\nelse.\n\nSome of the mismatches change what the reader understands. The string 10/11/2026\nis 11 October to an American reader and 10 November to a British one; both are\nvalid dates, so nothing fails, and one of the two readers acts on the wrong day.\nThe string 1,234 is one thousand two hundred and thirty-four in English and one\npoint two three four in Danish, a factor of a thousand in a quantity or a price.\nA wrong translation looks wrong. A wrong convention looks right and is read\nwrongly.\n\nThe W3C's list also reaches past the screen. Legal requirements differ between\nmarkets, and so does the way a business is run, so a locale can need different\nterms, different invoice details or a different flow through a purchase. These\nare decisions for the business, and they belong in the plan for a locale before\nthe first message is translated.\n\nThe cost is per locale and it does not end. Every new message has to be\ntranslated into every language, every release has to be read in every locale\nbefore it ships, and every market brings its own conventions to check. A team\nthat adds a language adds that work to each later release, which is why the\ndecision to enter a market is also a decision about the release process.\n\n## What it looks like in practice\n\nThe platform does most of the work when the code passes it a value and a locale.\nIn JavaScript, the `Intl` formatters take both and return text:\n\n```js\nconst when = new Date(\"2026-10-27T12:00:00Z\");\nconst money = { style: \"currency\", currency: \"DKK\" };\nfor (const locale of [\"en-US\", \"en-GB\", \"da\", \"nb\", \"sv\", \"uk\"]) {\n  const date = new Intl.DateTimeFormat(locale, { dateStyle: \"short\" });\n  const price = new Intl.NumberFormat(locale, money);\n  console.log(locale, date.format(when), price.format(800));\n}\n```\n\nRun in Node.js 25, which carries data from CLDR 47, it prints one date and one\nprice of 800 Danish kroner six ways:\n\n```text\nen-US 10/27/26 DKK 800.00\nen-GB 27/10/2026 DKK 800.00\nda 27.10.2026 800,00 kr.\nnb 27.10.2026 800,00 DKK\nsv 2026-10-27 800,00 Dkr\nuk 27.10.26 800,00 DKK\n```\n\nThe code chose none of it. The Danish reader sees kr., the Swedish reader Dkr,\nbecause kr in Sweden means the Swedish krona, and the Norwegian and Ukrainian\nreaders see the currency code. The order of day and month, the separators, the\ndecimal comma and the place of the currency all come from the locale data. In\nthe real output the space between the amount and its currency is a no-break\nspace, U+00A0, which keeps the two on one line.\n\nSorting works the same way. A list of six Danish place names, sorted for three\nlocales:\n\n```js\nconst towns = [\"Aabenraa\", \"Ærø\", \"Åkirkeby\", \"Odense\", \"Østerbro\", \"Vejle\"];\nfor (const locale of [\"en\", \"da\", \"sv\"]) {\n  const order = new Intl.Collator(locale).compare;\n  console.log(locale, towns.toSorted(order).join(\", \"));\n}\n```\n\n```text\nen Aabenraa, Ærø, Åkirkeby, Odense, Østerbro, Vejle\nda Odense, Vejle, Ærø, Østerbro, Aabenraa, Åkirkeby\nsv Aabenraa, Odense, Vejle, Åkirkeby, Ærø, Østerbro\n```\n\nEnglish treats æ, ø and å as forms of a and o. Danish places Æ, Ø and Å after Z\nand files the old spelling Aa as Å, so Aabenraa moves from first to next to\nlast. Swedish puts its own Å, Ä and Ö after Z and files Æ with Ä and Ø with Ö.\nEach order is correct for its readers, and a Danish reader who looks for\nAabenraa near the end of a list sorted for English has reason to think it is\nmissing.\n\nA Hugo site has the same tools in its templates. Hugo's documentation passes one\namount through `lang.FormatCurrency`:\n\n```text\n{{ 512.5032 | lang.FormatCurrency 2 \"USD\" }}\n```\n\nAn English page shows it as $512.50, a French one as 512,50 $US and a German one\nas 512,50 $, and `lang.FormatNumber` and `lang.FormatPercent` do the same for\nplain numbers and percentages.\n\nLocalization is part of one of this site's services. The\n[internationalization and localization service](/services/i18n-localization/)\ndescribes the aim as software that reads naturally in every market a client\nsells in, including the dates, the currencies and the way names sort. Among its\nresults is a cross-language content check that fails when a translation drops a\nfigure the English states, or when a language uses notation it does not use, and\nthat found two Danish descriptions missing a metric and sixteen Ukrainian spans\nquoting in the English style.\n\n## Where it goes wrong\n\n**Localization is budgeted as translation.** The plan for a new market covers\nthe message files and nothing else, so the product launches in the new language\nwith the old market's dates, prices, addresses and sort order, and the gaps are\nfound by customers. Plan each locale against the W3C's whole list, decide which\nitems apply to that market, and have a native reader review the built product\nrather than the message files.\n\n**A language is taken for a locale.** `en` does not say whether 27 October is\n`10/27/26` or `27/10/2026`, and the output above shows that the two English\nlocales disagree on both the order and the year. A product that stores only the\nlanguage must guess the rest, and it guesses one market's conventions for every\nother. Keep a full tag such as `en-GB` or `da-DK` for each user, take it from an\nexplicit setting where there is one, and pass it to every formatter.\n\n**The currency is guessed from the locale.** CLDR's specification is blunt about\nit: an amount should never be passed between systems without a known currency\ncode, or the same number 3.5 may end up \"interpreted as $3.50 by one user and\n€3.50 by another.\" It adds that the currency of an amount is independent of the\nreader's language and that only badly designed software leaves the code out and\ninfers it from the locale. In Scandinavia the guess goes wrong quietly, because\nDanish, Norwegian and Swedish each abbreviate their own currency kr, so a price\nstored as 800 reads as 800 Danish kroner to one reader and 800 Norwegian kroner\nto the next. Store every amount with its ISO 4217 code and format it for the\nreader; a Danish reader then sees a Norwegian price as 800,00 NOK.\n\n**Lists are sorted by code point.** JavaScript's default `sort` compares UTF-16\ncode units, which puts Є and І before the rest of the Ukrainian alphabet and Ґ\nafter Я, because their code points lie outside the range that runs from А to я.\nSorted that way, `[\"Ялта\", \"Ґанок\", \"Гора\", \"Єнот\", \"Іван\", \"Дуб\"]` comes out as\nЄнот, Іван, Гора, Дуб, Ялта, Ґанок; with `new Intl.Collator(\"uk\").compare` it is\nГора, Ґанок, Дуб, Єнот, Іван, Ялта, the order of the Ukrainian alphabet. Sort\ntext for display with a collator for the reader's locale, in the code or in the\ndatabase's collation, and keep code-point order for keys that no reader sees.\n\n**Tests compare formatted text typed by hand.** A test that expects `800,00 kr.`\nwith an ordinary space fails against the formatter, which puts U+00A0 there, and\nthe same no-break space separates the thousands in Norwegian, Swedish and\nUkrainian. Locale data is also revised from one CLDR release to the next, so a\nstring that matched before a platform upgrade may not match after it. Build the\nexpected text with the same formatter and locale the code uses, or assert on the\nstored value and the locale passed in rather than on the rendered string.\n\n**The layout is sized for English.** A button that fits Save has to fit\nЗберегти, twice as many letters, and a menu that fits Settings has to fit the\nDanish Indstillinger. Fixed widths cut the longer word off or push it onto a\nsecond line, and often the first to see it is a reader in that market. Let\ncontainers grow with their text, avoid fixed widths around translated words, and\nreview every locale at the narrowest screen the product supports.\n\n## Further reading\n\n- [Localization vs. Internationalization](https://www.w3.org/International/questions/qa-i18n#l10n)\n  — the W3C's working definition of localization, its list of what a locale may\n  need adapted, and how localization relates to internationalization.\n- [Hugo: Multilingual mode](https://gohugo.io/content-management/multilingual/)\n  — localized dates, currencies, numbers and percentages in Hugo templates,\n  alongside translation tables and per-language URLs.\n- [UTS #35, Part 3: Numbers](https://www.unicode.org/reports/tr35/tr35-numbers.html)\n  — CLDR's number and currency formats, including the rule that an amount\n  always travels with its currency code.\n- [Unicode CLDR Project](https://cldr.unicode.org/) — the project that collects\n  locale data for over 100 languages and supplies it to operating systems,\n  browsers and programming languages.\n\n\u003chttps://engineer.company/glossary/localization/\u003e\n","date_modified":"2026-10-30T02:51:31Z","description":"What localization adapts beyond translation, where dates, prices and sort order come from, and six ways a product misreads the market it is sold in.","formats":{"gemtext":"https://engineer.company/glossary/localization/index.gmi","gopher":"https://engineer.company/glossary/localization/gophermap","html":"https://engineer.company/glossary/localization/","json":"https://engineer.company/glossary/localization/index.json","markdown":"https://engineer.company/glossary/localization/index.md","pdf":"https://engineer.company/glossary/localization/index.pdf"},"kind":"page","language":"en","title":"What is localization?","url":"https://engineer.company/glossary/localization/","version":1}