docs(ui): expand bilingual component guides

packages/ui/docs/en-US/advanced/localization.mdx

@@ -1,19 +1,29 @@
 ---
 title: Localize UI
-description: Load only the UI catalog and calendar locale required by the active language.
+description: Bridge the application translator into UI components and load the active calendar locale.
 order: 21
 toc:
-  - id: catalog-source
-    title: Catalog source
-  - id: direct-imports
-    title: Direct imports
-  - id: supported-locales
-    title: Supported locales
+  - id: two-layers
+    title: Two responsibilities
+  - id: catalogs
+    title: Merge catalogs
+  - id: bridge-provider
+    title: Bridge the provider
+  - id: fallback
+    title: Fallback behavior
+  - id: direction
+    title: Text direction
 ---
 
-## Catalog source {#catalog-source}
+## Two responsibilities {#two-layers}
 
-Add the UI locale source to the application's internationalization configuration:
+`@workspace/i18n` manages the application locale, catalog loading, formatting, and switching. `@workspace/ui/components/i18n` is a small adapter that keeps UI primitives independent of an internationalization framework. It accepts a compatible translator, a language tag, and a `react-day-picker` locale.
+
+This separation keeps the UI package reusable while allowing applications to use the full workspace internationalization runtime.
+
+## Merge catalogs {#catalogs}
+
+Add the UI catalog source to the application's `i18n.config.json`:
 
 ```json
 {
@@ -21,16 +31,50 @@ Add the UI locale source to the application's internationalization configuration
 }
 ```
 
-The locales root contains metadata and types. It does not import every language catalog.
+The `@workspace/ui/locales` root exports only `uiCatalogLocales`, `uiMessageIds`, and types; it does not statically import every language. The current supported set is `en-US` and `zh-Hans`.
 
-## Direct imports {#direct-imports}
+## Bridge the provider {#bridge-provider}
 
-```ts
-import { calendarLocale, messages } from "@workspace/ui/locales/en-US"
+Read the translator from the current application provider and pass it to the UI provider:
+
+```tsx
+import { useLocaleDefinition, useTranslate } from "@workspace/i18n"
+import {
+  I18nProvider as UiI18nProvider,
+  type CalendarLocale,
+} from "@workspace/ui/components/i18n"
+import { calendarLocale as enUS } from "@workspace/ui/locales/en-US"
+import { calendarLocale as zhHans } from "@workspace/ui/locales/zh-Hans"
+
+const calendarLocales: Record<string, CalendarLocale> = {
+  "en-US": enUS,
+  "zh-Hans": zhHans,
+}
+
+export function AppUiI18nProvider({ children }: React.PropsWithChildren) {
+  const locale = useLocaleDefinition()
+  const t = useTranslate()
+
+  return (
+    <UiI18nProvider
+      calendarLocale={calendarLocales[locale.locale]}
+      locale={locale.languageTag ?? locale.locale}
+      t={t}
+    >
+      {children}
+    </UiI18nProvider>
+  )
+}
 ```
 
-Each language entry also exports its matching `react-day-picker` locale.
+`Calendar` prefers its own `locale` prop, then the provider's `calendarLocale`. Month formatting and the default `lang` use the provider language tag.
 
-## Supported locales {#supported-locales}
+## Fallback behavior {#fallback}
 
-The UI catalogs include American English (`en-US`) and Simplified Chinese (`zh-Hans`).
+Without a provider, the UI layer uses `en-US` and the English source text from each descriptor. Isolated tests and stories therefore remain usable, but production applications should bridge the provider so accessible names and visible text use the same locale.
+
+Custom components may use `uiMessages`, `useMessage`, `useTranslate`, `LocalizedText`, `useLocale`, and `useCalendarLocale`. Product copy belongs in the application or domain package, not in the UI catalog.
+
+## Text direction {#direction}
+
+Translation locale and layout direction are separate concerns. When switching locales, the application should synchronize `document.documentElement.lang` and `dir`, and use `DirectionProvider` when needed. Local components use logical utilities such as `start`, `end`, `ps`, and `pe`; `components.json` also enables `rtl` generation.