# Documentation for AI agents

This file is generated at build time from the Markdown documentation. Use it to choose the most relevant page before reading the canonical HTML documentation.

## Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/
Source: docs/index.md
Description: Drop-in internationalization primitives for Web Components, built for readable, composable, runtime-safe localized interfaces.

::: layout landing-hero version="v0.1.0" title="Internationalization" title2="in plain HTML." primaryLabel="Get Started" secondaryLabel="$ npm i @beforesemicolon/intl" === copy Drop-in localization primitives for Web Components. Format messages, numbers, dates, durations, relative time, lists, display names, and plural

## Why Intl? - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/
Source: docs/documentation/index.md
Description: Learn why Intl provides HTML-first localization primitives for Web Components and component-first interfaces.

Why Intl? @beforesemicolon/intl gives component-first applications a predictable localization layer. It combines: - runtime-aware locale scoping - message lookup and fallback behavior - formatting helpers for numbers, dates, durations, relative time, names, lists, and plurals Everything is explicit, so you can reason a

## Get Started - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/get-started
Source: docs/documentation/get-started.md
Description: Build your first multilingual UI with one runtime scope and reusable formatters.

Get started Use this page to get a working localized UI quickly. Start with a runtime scope, then add tags and helper calls as you expand the page. Step 1 — Initialize a locale scope This creates one locale runtime boundary and loads translation files from /locales/en-US.json. Step 2 — Render translated text <intl-msg 

## Installation - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/installation
Source: docs/documentation/installation.md
Description: Install Intl for browser CDN usage or module usage in any framework.

Install @beforesemicolon/intl is designed to work in plain HTML, any framework, and tests. You have two options: - package manager + module usage - CDN + browser globals Both approaches expose the same runtime behavior. Via package manager Then initialize the runtime from your app entrypoint: Use any exported helpers d

## Intl Guide & Best Practices - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/guide-best-practices
Source: docs/documentation/guide-best-practices.md
Description: Practical guidance for building maintainable HTML-first localization with Before Semicolon Intl.

Guide & Best Practices Use this guide to keep localized UIs predictable at scale. The package is most effective when locale scope and content remain explicit. 1) Start with one top-level <intl-locale Use one top-level provider for the page when possible. It centralizes: - message loading - locale fallback behavior - do

## <intl-locale> - Runtime Scope

URL: https://intl.beforesemicolon.com/documentation/components/intl-locale
Source: docs/documentation/components/intl-locale.md
Description: Define locale runtime boundaries, load messages, update document language, and scope child Intl components.

<intl-locale <intl-locale creates the runtime scope used by every Intl component inside it. Use it around the part of the page that should share a locale, message source, fallback locale, and text direction. Native mapping: locale detection and direction follow Intl.Locale. Attributes | Attribute | Type | Default | Des

## <intl-msg> - Message Formatter

URL: https://intl.beforesemicolon.com/documentation/components/intl-msg
Source: docs/documentation/components/intl-msg.md
Description: Resolve runtime messages by key with text fallback and placeholder interpolation.

<intl-msg <intl-msg renders a message from the nearest <intl-locale runtime. Its child text is the fallback shown before messages are ready, when a key is missing, or when no key is provided. Attributes | Attribute | Type | Default | Description | |---|---|---|---| | key | string | '' | Dot-path message key, such as ch

## <intl-number> - Number Formatter

URL: https://intl.beforesemicolon.com/documentation/components/intl-number
Source: docs/documentation/components/intl-number.md
Description: Format numbers, currencies, percentages, units, compact notation, digit ranges, and numbering systems.

<intl-number <intl-number formats a numeric value with Intl.NumberFormat. Prefer child text for simple values so you keep readable fallback content before JS upgrades the component. Native reference: Intl.NumberFormat Attributes and properties | Attribute | JS property | Type | Description | |---|---|---|---| | value |

## <intl-datetime> - Date & Time Formatter

URL: https://intl.beforesemicolon.com/documentation/components/intl-datetime
Source: docs/documentation/components/intl-datetime.md
Description: Format Date, timestamp, and date string values with Intl.DateTimeFormat options.

<intl-datetime <intl-datetime formats a date value and renders a <time element with a machine-readable datetime attribute. Native references: Intl.DateTimeFormat and <time element Attributes and properties | Attribute | JS property | Type | Description | |---|---|---|---| | value | value | string/number/Date | Date val

## <intl-duration> - Duration Formatter

URL: https://intl.beforesemicolon.com/documentation/components/intl-duration
Source: docs/documentation/components/intl-duration.md
Description: Format millisecond durations with selected fields and long, short, narrow, or digital styles.

<intl-duration <intl-duration formats a millisecond duration and breaks the value into duration fields. It uses Intl.DurationFormat when available, otherwise a package fallback formatter. Native reference: Intl.DurationFormat Attributes and properties | Attribute | JS property | Type | Description | |---|---|---|---| |

## <intl-rel-time> - Relative Time Formatter

URL: https://intl.beforesemicolon.com/documentation/components/intl-relative-time
Source: docs/documentation/components/intl-relative-time.md
Description: Render relative timestamps or unit offsets with live updates and accessible labels.

<intl-rel-time <intl-rel-time formats relative time with Intl.RelativeTimeFormat. It renders a <time element when unit="auto" can be represented as an absolute timestamp. Native reference: Intl.RelativeTimeFormat The package also registers <intl-relative-time as an equivalent element name. Attributes and properties | A

## <intl-list> - List Formatter

URL: https://intl.beforesemicolon.com/documentation/components/intl-list
Source: docs/documentation/components/intl-list.md
Description: Format localized conjunction, disjunction, and unit lists from child text or a value.

<intl-list <intl-list formats a list with Intl.ListFormat. Child text is split on whitespace. The helper function can also accept arrays. Native reference: Intl.ListFormat Attributes and properties | Attribute | JS property | Type | Description | |---|---|---|---| | value | value | string/string[] | List source. Child 

## <intl-name> - Display Names

URL: https://intl.beforesemicolon.com/documentation/components/intl-name
Source: docs/documentation/components/intl-name.md
Description: Render localized names for regions, languages, scripts, and currencies.

<intl-name <intl-name resolves identifiers through Intl.DisplayNames. Native reference: Intl.DisplayNames Attributes and properties | Attribute | JS property | Type | Description | |---|---|---|---| | value | value | string | Identifier to display. Child text is used when omitted. | | locale | locale | string | Overrid

## <intl-plural> - Pluralization

URL: https://intl.beforesemicolon.com/documentation/components/intl-plural
Source: docs/documentation/components/intl-plural.md
Description: Select cardinal and ordinal plural text from locale-aware Intl.PluralRules categories.

<intl-plural <intl-plural selects a plural category from locale rules and renders the matching category text. Native reference: Intl.PluralRules Attributes and properties | Attribute | JS property | Type | Description | |---|---|---|---| | value | value | number/string | Number to classify. Child text is used when omit

## intlMsg - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-message
Source: docs/documentation/formatters/intl-message.md
Description: Resolve a message key from an Intl runtime and interpolate placeholder values.

intlMsg intlMsg(key, values?, options?) resolves a message key from runtime messages and returns a plain string. Use this for server-side rendering, app-level formatting, and logic where you need only the text result. It matches message behavior used by <intl-msg so keys and placeholders are consistent across JS + comp

## intlNumber - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-number
Source: docs/documentation/formatters/intl-number.md
Description: Format decimal, currency, percent, unit, compact, and rounded numbers with Intl.NumberFormat.

intlNumber intlNumber(value, options?) formats numeric values with locale-aware number patterns. Use this for price, percentage, metrics, compact values, and measurement units. Native reference: Intl.NumberFormat Signature Invalid numbers return ''. Option map | Option | Type | Default | Effect | |---|---|---|---| | lo

## intlDateTime - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-date-time
Source: docs/documentation/formatters/intl-date-time.md
Description: Format Date, timestamp, and ISO string values with Intl.DateTimeFormat.

intlDateTime intlDateTime(value, options?) formats a date-like value as localized date/time text. Use this for values you already have in JS and want the same output as <intl-datetime. It uses the same option model as: Intl.DateTimeFormat and uses the same runtime locale resolution as components. Native output context:

## intlDuration - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-duration
Source: docs/documentation/formatters/intl-duration.md
Description: Format millisecond durations into localized duration strings.

intlDuration intlDuration(value, options?) converts milliseconds to human-readable duration text. Use it for time spans (API delays, countdowns, file-size elapsed windows, etc.). It mirrors Intl.DurationFormat behavior and falls back to a package implementation when that API is unavailable. Input shape value should be 

## intlRelTime - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-relative-time
Source: docs/documentation/formatters/intl-relative-time.md
Description: Format relative timestamps or unit offsets with Intl.RelativeTimeFormat.

intlRelTime intlRelTime(value, options?) formats relative values for times like: - 0 - now (subject to locale rules) - -1 - past - 1 - future It supports: - unit: 'auto' (absolute timestamp compared to Date.now()) - explicit units (year, day, minute, etc.) Native reference: Intl.RelativeTimeFormat Signature Invalid num

## intlList - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-list
Source: docs/documentation/formatters/intl-list.md
Description: Format localized lists with Intl.ListFormat.

intlList intlList(value, options?) builds a localized list string from multiple values. Use it for breadcrumb-like segments, summaries, or UI helper text like shipping/payment terms. It maps directly to: Intl.ListFormat Input shape value can be: - string[] - space-separated text ("A B C") Signature Invalid or empty inp

## intlName - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-name
Source: docs/documentation/formatters/intl-name.md
Description: Display localized language, region, script, and currency names with Intl.DisplayNames.

intlName intlName(value, options?) converts identifiers into localized human names. Use this for country labels, currency names, script names, and language names. Native reference: Intl.DisplayNames Signature Empty or unknown values return ''. Option map | Option | Type | Default | Effect | |---|---|---|---| | locale |

## intlPlural - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/formatters/intl-plural
Source: docs/documentation/formatters/intl-plural.md
Description: Select cardinal or ordinal plural output with Intl.PluralRules.

intlPlural intlPlural(value, options?) returns text based on locale plural rules. Use this for item labels, counters, and plural-aware grammar in any output path. Native reference: Intl.PluralRules Signature Invalid values return ''. Option map | Option | Type | Default | Effect | |---|---|---|---| | locale | string | 

## createIntl - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/create-intl
Source: docs/documentation/apis/create-intl.md
Description: Create an isolated Intl runtime for a component region, micro-app, or integration boundary.

createIntl createIntl(options?) creates a standalone localization runtime. Use it when one part of the app needs its own locale state, loading strategy, or message source while keeping the rest of the app unchanged. The key difference from initIntl() is scope: - initIntl() creates/replaces the package default runtime (

## initIntl - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/init-intl
Source: docs/documentation/apis/init-intl.md
Description: Initialize or replace the default Intl runtime used by helper functions and unscoped components.

initIntl initIntl(options?) creates or replaces the package default runtime. Use this at app entry, when one locale baseline should apply across the whole page. Native API: Intl.Locale Signature What happens when called - destroys any existing default runtime - creates a new default runtime from options - default runti

## getIntl - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/get-intl
Source: docs/documentation/apis/get-intl.md
Description: Read the active Intl runtime, either from an explicit scope or from the package default runtime.

getIntl getIntl(scope?) gives you the runtime instance that formatters and components use. Use it when you need to inspect current state, read messages directly, or share one runtime instance between modules. Signature How it chooses scope - If you pass a scope, it returns that runtime directly. - If you omit scope, it

## setLocale - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/set-locale
Source: docs/documentation/apis/set-locale.md
Description: Change the active locale on a runtime and load messages for the new locale.

setLocale setLocale(locale, scope?) updates the runtime locale and loads the locale payload for that runtime. It is the supported path for in-page language switching. Signature What changes when this runs - sets runtime locale - marks runtime status as loading - loads locale messages (src / srcDir or custom loader) - l

## loadLocale - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/load-locale
Source: docs/documentation/apis/load-locale.md
Description: Load messages for the current or requested locale without necessarily changing the active runtime locale.

loadLocale loadLocale(locale?, scope?) triggers message loading for a runtime. It never changes runtime.locale by itself. It only fetches and stores messages. Signature Preload and warm cache Preloading keeps a second locale ready for quick switching while keeping current runtime locale unchanged. Error handling snapsh

## subscribeIntl - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/subscribe-intl
Source: docs/documentation/apis/subscribe-intl.md
Description: Subscribe to Intl runtime snapshots when locale, loading status, or messages change.

subscribeIntl subscribeIntl(listener, scope?) subscribes to live runtime snapshots. It is useful for UI that must react to locale, loading, or message load state outside components. Signature Callback contract subscribeIntl does two things immediately: 1. adds the listener 2. calls it once with the current snapshot It 

## destroyIntl - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/destroy-intl
Source: docs/documentation/apis/destroy-intl.md
Description: Destroy the default or scoped Intl runtime and clear subscriptions, caches, and pending loads.

destroyIntl destroyIntl(scope?) disposes runtime resources. Use this for component/page teardown in long-lived single-page contexts. Signature What it does - cancels pending loads via AbortController - clears listeners, loading maps, and runtime caches - clears loaded locale maps - marks runtime as destroyed If no scop

## resetIntl - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/reset-intl
Source: docs/documentation/apis/reset-intl.md
Description: Reset the package default Intl runtime, mainly for tests and controlled runtime teardown.

resetIntl resetIntl() destroys and removes the package default runtime. This is the cleanest reset strategy for tests, demos, and repeated bootstraps in the same process. Signature What gets cleared - default runtime object - listeners and subscriptions tied to the default runtime - loaded messages and in-flight locale

## getLocaleDirection - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/get-locale-direction
Source: docs/documentation/apis/get-locale-direction.md
Description: Resolve text direction for a locale using Intl.Locale.

getLocaleDirection getLocaleDirection(locale) returns text direction for a locale tag: - 'rtl' for right-to-left locales - 'ltr' for left-to-right locales This function uses Intl.Locale. Signature Practical notes - invalid locale values return 'ltr' instead of throwing - this is useful for pre-setting dir before runtim

## onLocaleMessagesLoaded - Intl by Before Semicolon

URL: https://intl.beforesemicolon.com/documentation/apis/on-locale-messages-loaded
Source: docs/documentation/apis/on-locale-messages-loaded.md
Description: Register the intl-locale component and return locale lifecycle behavior for the browser entrypoint.

onLocaleMessagesLoaded onLocaleMessagesLoaded is exported from the browser bundle and used when you load dist/client.js. It ties locale events to the custom-element layer so DOM workflows can react to runtime lifecycle without importing the full module API. Signature Event model and lifecycle The helper powers the same