<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.
1<intl-locale locale="en-US" fallback-locale="en" src-dir="/locales">2 <intl-msg key="checkout.title">Checkout</intl-msg>3 <intl-number type="currency" currency="USD">1299.99</intl-number>4</intl-locale>Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
locale | string | html[lang] or en | Active locale for this scope. |
fallback-locale | string | en | Locale used for fallback message loading and message lookup. |
src | string | undefined | Exact JSON endpoint for this locale scope. |
src-dir | string | /locales | Directory used as ${srcDir}/${locale}.json when src is not set. |
update-document | boolean attribute | absent | Updates document.documentElement.lang and dir from the runtime snapshot. |
fallback | boolean attribute | absent | Renders children immediately while locale messages load. Without it, children render after the runtime is ready. |
Lifecycle events
Events bubble and are composed, so you can listen from a parent container or document.body.
| Event | When it fires | event.detail |
|---|---|---|
locale-load | Message loading completes. | IntlRuntimeSnapshot |
locale-change | The locale is ready after load or change. | IntlRuntimeSnapshot |
locale-error | Message loading fails. | IntlRuntimeSnapshot with error |
locale
locale sets the active locale for every Intl component inside the scope.
1<intl-locale locale="en-US" src-dir="/locales">2 <intl-msg key="home.title">Home</intl-msg>3 <intl-number>1299.99</intl-number>4</intl-locale>5 6<intl-locale locale="fr-FR" src-dir="/locales">7 <intl-msg key="home.title">Home</intl-msg>8 <intl-number>1299.99</intl-number>9</intl-locale>When locale is omitted, the runtime uses document.documentElement.lang when available, then falls back to en.
fallback-locale
fallback-locale is used when messages for the active locale are missing or incomplete.
1<intl-locale locale="pt-CV" fallback-locale="pt" src-dir="/locales">2 <intl-msg key="home.title">Home</intl-msg>3</intl-locale>With this setup, the runtime loads /locales/pt-CV.json and can use /locales/pt.json as fallback messages.
src
Use src when the locale scope should load one exact JSON endpoint.
1<intl-locale locale="en-US" src="/api/messages/current-user">2 <intl-msg key="dashboard.title">Dashboard</intl-msg>3</intl-locale>src can also point to a page-specific JSON file.
1<intl-locale locale="en" src="/locales/en.landing-page.json">2 <section>3 <h1><intl-msg key="hero.title">Internationalization in plain HTML.</intl-msg></h1>4 <p><intl-msg key="hero.summary">Format messages close to the UI.</intl-msg></p>5 </section>6</intl-locale>Use this for route-level or page-level message splitting when a page should load a smaller locale file.
src-dir
Use src-dir when every locale follows the same directory convention.
1<intl-locale locale="pt-CV" fallback-locale="en" src-dir="/locales">2 <intl-msg key="home.title">Home</intl-msg>3</intl-locale>This loads:
1/locales/pt-CV.json2/locales/en.jsonUse src-dir for app-wide bundles. Use src for exact files such as /locales/en.landing-page.json.
update-document
update-document keeps the page-level lang and dir attributes synchronized with this runtime.
1<intl-locale locale="ar" src-dir="/locales" update-document>2 <intl-msg key="home.title">Home</intl-msg>3</intl-locale>After loading, the document can be updated like this:
1<html lang="ar" dir="rtl">Use this on the root page locale. Avoid using it on small nested scopes unless that nested scope should control the whole document language.
fallback
By default, children render after the runtime is ready. Add fallback when fallback text should render immediately while messages load.
1<intl-locale locale="en-US" src-dir="/locales" fallback>2 <h1><intl-msg key="home.title">Home</intl-msg></h1>3</intl-locale>Without fallback, the slot waits for the runtime. With fallback, child components can render their child text first and update when messages arrive.
locale-load
Listen for locale-load when you need to know that a load attempt completed.
1<intl-locale id="app-locale" locale="fr-FR" src-dir="/locales"></intl-locale>2 3<script>4 document.getElementById('app-locale').addEventListener('locale-load', (event) => {5 console.log(event.detail.locale)6 console.log(event.detail.status)7 })8</script>locale-change
Listen for locale-change when UI should react to a ready locale.
1<intl-locale id="settings-locale" locale="en" src-dir="/locales" fallback>2 <select id="language">3 <option value="en">English</option>4 <option value="fr">French</option>5 </select>6 7 <intl-msg key="settings.title">Settings</intl-msg>8</intl-locale>9 10<script>11 const locale = document.getElementById('settings-locale')12 const language = document.getElementById('language')13 14 language.addEventListener('change', () => {15 locale.runtime.setLocale(language.value)16 })17 18 locale.addEventListener('locale-change', (event) => {19 language.value = event.detail.locale20 })21</script>locale-error
Listen for locale-error when you want custom error handling for failed message loads.
1<intl-locale id="app-locale" locale="fr-FR" src="/missing/fr.json">2 <intl-msg key="home.title">Home</intl-msg>3</intl-locale>4 5<script>6 document.getElementById('app-locale').addEventListener('locale-error', (event) => {7 console.error(event.detail.error)8 })9</script>Nested locale scopes
A nested provider uses the nearest scope. It can inherit parent messages and fallback configuration, then override them with its own loaded messages.
1<intl-locale locale="en-US" src-dir="/locales">2 <intl-msg key="product.name">Product</intl-msg>3 4 <intl-locale locale="fr-FR" src-dir="/locales">5 <intl-msg key="product.name">Produit</intl-msg>6 </intl-locale>7</intl-locale>Nested scopes are useful for previews, embedded widgets, language switchers, and side-by-side localization QA.
Page-scoped locale bundles
Page-scoped bundles let each page load only the messages it needs instead of fetching one large locale bundle for the whole site.
For example, keep shared and page messages separate in source:
1locales/common.json2locales/landing-page.jsonAt build time, merge those files for each locale and emit a page bundle:
1locales/en.landing-page.jsonThen wrap the landing page with an exact source:
1<intl-locale locale="en" src="/locales/en.landing-page.json">2 <h1><intl-msg key="hero.title">Internationalization in plain HTML.</intl-msg></h1>3</intl-locale>