LocaleProvider handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Set the language of built-in SnowUI interface labels for an application or subtree, with optional message overrides.

When to use it

Set the language or override built-in labels for descendant components. The application remains responsible for translating its own titles and data. Explicit component labels take precedence over the provider, which renders no visible wrapper.

• locale selects the built-in language; messages overrides labels in the provider subtree. Explicit component labels take precedence.

• children render in place without an added wrapper. The application still manages translation of its own titles and data.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { LocaleProvider, Frame, Pagination, Text } from '@snowui-design-system/components';</script> <LocaleProvider locale="en-US">	<Frame column style="align-items: stretch; gap: var(--gap-2); width: min(100%, 32rem);">		<Text weight={600}>English documentation controls</Text>		<Pagination page={2} total={6} widthMode="hug" ariaLabel="Component documentation pages" />	</Frame></LocaleProvider>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Examples

<LocaleProvider locale="en-US">    <SidePanel open editable /></LocaleProvider>

Site guide: locale-provider

How LocaleProvider works {#overview}

LocaleProvider supplies language context to descendant components. It adds no HTML wrapper, visual style, or layout of its own. Place it around the part of your application that should share a language.

It translates supported built-in messages, such as dialog close labels and color-scheme controls. Your page titles, content, and application messages remain owned by your application.

Import {#import}

LocaleProvider is included in the publicly downloadable Components package under the SnowUI license. Follow Quick Start to install the package and load the shared stylesheet.

import { LocaleProvider } from '@snowui-design-system/components';

Choose a language {#locale}

The default language is zh-CN. Set locale="en-US" for the built-in English catalog. The following color-scheme control receives its accessible label from the surrounding provider.

<script lang="ts">  import { ColorSchemeButton, LocaleProvider } from "@snowui-design-system/components";</script> <LocaleProvider locale="en-US">  <ColorSchemeButton /></LocaleProvider>

Change language at runtime {#switch-language}

Pass reactive state to locale to update supported built-in messages without recreating the provider. Store the selected language in your application if it should persist between visits.

<script lang="ts">  import { ColorSchemeButton, LocaleProvider } from "@snowui-design-system/components";  let locale = $state("en-US");</script> <label>  Interface language  <select bind:value={locale}>    <option value="en-US">English</option>    <option value="zh-CN">Simplified Chinese</option>  </select></label> <LocaleProvider {locale}>  <ColorSchemeButton /></LocaleProvider>

Customize built-in messages {#messages}

Use messages to override specific catalog keys inside the provider. Omitted keys continue to use the selected language. Use the component’s explicit label property when the wording belongs to just one instance.

This example changes the two accessible labels used by ColorSchemeButton. Message keys are specific to the component; arbitrary application translation keys are not part of this catalog.

<script lang="ts">  import { ColorSchemeButton, LocaleProvider } from "@snowui-design-system/components";</script> <LocaleProvider locale="en-US" messages={{  "colorSchemeButton.toLight": "Use light appearance",  "colorSchemeButton.toDark": "Use dark appearance"}}>  <ColorSchemeButton /></LocaleProvider>

Scope and nested providers {#scope}

Each component reads the nearest LocaleProvider. A nested provider establishes its own locale and messages; it does not merge overrides from its parent. Declare the nested locale explicitly to make that boundary clear.

Here, the first control uses English and the second uses Chinese. Neither setting changes components outside its provider.

<script lang="ts">  import { ColorSchemeButton, LocaleProvider } from "@snowui-design-system/components";</script> <LocaleProvider locale="en-US">  <ColorSchemeButton />  <LocaleProvider locale="zh-CN">    <ColorSchemeButton />  </LocaleProvider></LocaleProvider>

Overrides and fallbacks {#fallbacks}

Messages resolve in this order: an explicit component label, provider messages, the selected language catalog, the default zh-CN catalog, and finally the message key.

The current built-in catalogs are zh-CN and en-US. Resolution tries the exact locale, then a registered language-only catalog, then zh-CN. No language-only catalogs are currently registered: use en-US rather than assuming en or en-GB will resolve to English.

Application content and formatting {#application-content}

LocaleProvider does not translate arbitrary children or change the document’s lang or dir attributes. Keep those attributes and your application translations in sync with the language selected by your application.

Use the documented locale and formatting options of date and number components for formatted values. This provider’s public contract covers built-in UI messages; it does not promise to reformat every date or number in the application.

Next steps {#next-steps}

• Quick Start

• ColorSchemeButton

• Dialog