{
    "slug": "js_intl",
    "term": "Intl API",
    "category": "javascript",
    "difficulty": "intermediate",
    "short": "The built-in JavaScript internationalisation API — format numbers, dates, currencies, relative times, and lists correctly for any locale without external libraries.",
    "long": "The Intl API provides: Intl.NumberFormat (numbers, currencies, percentages), Intl.DateTimeFormat (dates, times with locale-aware formatting), Intl.RelativeTimeFormat ('2 days ago', 'in 3 hours'), Intl.ListFormat ('A, B, and C'), Intl.Collator (locale-aware string sorting), Intl.PluralRules (correct pluralisation per locale), and Intl.Segmenter (word/sentence boundaries). All major browsers support it. It handles locale-specific rules like Arabic RTL, German ordinal numbers, Japanese date formats, and Indian number grouping.",
    "aliases": [
        "Intl",
        "internationalisation",
        "i18n JavaScript",
        "NumberFormat",
        "DateTimeFormat"
    ],
    "tags": [
        "javascript",
        "i18n",
        "frontend"
    ],
    "misconception": "You need a library like moment.js or date-fns for locale-aware formatting — the built-in Intl API handles most formatting needs natively with no dependencies.",
    "why_it_matters": "Hardcoded date and number formats break for international users — Intl.DateTimeFormat and Intl.NumberFormat automatically apply the user's locale conventions with no extra code.",
    "common_mistakes": [
        "Creating a new Intl.NumberFormat on every call in a loop — formatters are expensive to construct; cache them.",
        "Not using navigator.language for the user's locale — hardcoding 'en-US' breaks for international users.",
        "Using Intl.RelativeTimeFormat without specifying the unit — 'days', 'hours' must be explicit.",
        "Forgetting Intl.Collator for sorting strings — standard < operator gives wrong order for accented characters."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "character_encoding",
        "i18n_pluralisation",
        "js_error_types"
    ],
    "prerequisites": [
        "php_intl_i18n",
        "unicode_basics",
        "locale_formatting"
    ],
    "refs": [
        "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl"
    ],
    "bad_code": "// Manual formatting — locale-unaware:\nconst price = '$' + amount.toFixed(2); // Wrong for non-US users\nconst date = month + '/' + day + '/' + year; // Ambiguous internationally\n\n// Wrong sort order for accented chars:\nwords.sort((a, b) => a < b ? -1 : 1); // Wrong for 'café' vs 'can'",
    "good_code": "// Intl API — automatic locale handling:\nconst price = new Intl.NumberFormat(navigator.language, {\n    style: 'currency', currency: 'USD'\n}).format(amount); // '1,234.56' (US) or '1.234,56 $' (DE)\n\nconst date = new Intl.DateTimeFormat(navigator.language, {\n    year: 'numeric', month: 'long', day: 'numeric'\n}).format(new Date()); // 'March 16, 2026' or '16. März 2026'\n\nconst relative = new Intl.RelativeTimeFormat(navigator.language)\n    .format(-2, 'day'); // '2 days ago' or 'il y a 2 jours'\n\nwords.sort(new Intl.Collator(navigator.language).compare); // Correct sort",
    "quick_fix": "Use Intl.NumberFormat, Intl.DateTimeFormat, and Intl.RelativeTimeFormat for all user-facing numbers, dates, and relative times — they respect the user's locale without any library",
    "severity": "medium",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/js_intl",
        "html_url": "https://codeclaritylab.com/glossary/js_intl",
        "json_url": "https://codeclaritylab.com/glossary/js_intl.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Intl API](https://codeclaritylab.com/glossary/js_intl) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/js_intl"
            }
        }
    }
}