From 0c3e288d141cdc2cf879ab14a34b5045b424ca0f Mon Sep 17 00:00:00 2001
From: nynexman4464 <1675576+nynexman4464@users.noreply.github.com>
Date: Tue, 10 Nov 2026 13:04:26 -0800
Subject: [PATCH] docs(InternationalizationProvider): order the examples
locale, RTL, overrides, calendar
---
.changeset/i18n-provider-example-order.md | 8 +++
...onalizationProvider01ShippedLocale.doc.mjs | 3 +-
...nationalizationProvider02Overrides.doc.mjs | 3 +-
...ionalizationProvider03RtlDirection.doc.mjs | 3 +-
...rnationalizationProvider04Calendar.doc.mjs | 3 +-
.../i18n/InternationalizationProvider.doc.mjs | 64 ++++++++++++-------
6 files changed, 58 insertions(+), 26 deletions(-)
create mode 100644 .changeset/i18n-provider-example-order.md
diff --git a/.changeset/i18n-provider-example-order.md b/.changeset/i18n-provider-example-order.md
new file mode 100644
index 0000000000000..dc0fca076490c
--- /dev/null
+++ b/.changeset/i18n-provider-example-order.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] InternationalizationProvider shows its examples in reading order: load a shipped locale, mirror the layout for right-to-left text (a new code example), override one string, then the calendar examples. Each live example is titled after its code example, so the two lists match.
+
+@nynexman4464
diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs
index da67c6de034cb..d9a20a5273424 100644
--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs
@@ -4,8 +4,9 @@
export const doc = {
type: 'block',
exampleFor: 'InternationalizationProvider',
- name: 'InternationalizationProvider — Shipped Locale',
+ name: 'Load a shipped Astryx locale catalog',
displayName: 'Internationalization Provider — Shipped Locale',
+ registry: {slug: 'shipped-locale'},
description:
'Load a locale catalog shipped by Astryx and re-render InternationalizationProvider with a new locale to update Astryx strings live.',
isReady: true,
diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs
index 8db75bc970fc8..8ad874689c173 100644
--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs
@@ -4,8 +4,9 @@
export const doc = {
type: 'block',
exampleFor: 'InternationalizationProvider',
- name: 'InternationalizationProvider — Overrides',
+ name: 'Override one Astryx string',
displayName: 'Internationalization Provider — Overrides',
+ registry: {slug: 'overrides'},
description:
'Override a small number of Astryx strings without providing a full locale catalog.',
isReady: true,
diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider03RtlDirection.doc.mjs b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider03RtlDirection.doc.mjs
index 6463971cc9b04..161f526222dcc 100644
--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider03RtlDirection.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider03RtlDirection.doc.mjs
@@ -4,8 +4,9 @@
export const doc = {
type: 'block',
exampleFor: 'InternationalizationProvider',
- name: 'InternationalizationProvider — RTL Direction',
+ name: 'Mirror the layout for right-to-left text',
displayName: 'Internationalization Provider — RTL Direction',
+ registry: {slug: 'rtl-direction'},
description:
'Toggle text direction with the `dir` prop and watch Astryx components mirror. Pagination flips its prev/next chevrons under RTL. The `dir` prop is passed to both `InternationalizationProvider` (so Astryx components pick it up) and the `VStack` (so the DOM subtree mirrors); both channels stay in sync with no extra wrapper.',
isReady: true,
diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider04Calendar.doc.mjs b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider04Calendar.doc.mjs
index 5b51ab398ebc0..a16d12735caff 100644
--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider04Calendar.doc.mjs
+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider04Calendar.doc.mjs
@@ -4,8 +4,9 @@
export const doc = {
type: 'block',
exampleFor: 'InternationalizationProvider',
- name: 'InternationalizationProvider — Calendar',
+ name: 'Show Calendar and DateInput in another calendar',
displayName: 'Internationalization Provider — Calendar',
+ registry: {slug: 'calendar'},
description:
'Set the `calendar` prop and the `Calendar` and `DateInput` inside the provider show that calendar system. The value stays a Gregorian ISO date. Japanese and Buddhist dates work in every browser; calendars such as Persian or Hebrew also need `Temporal` or a polyfill.',
isReady: true,
diff --git a/packages/core/src/i18n/InternationalizationProvider.doc.mjs b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
index 7f539c817dfa6..f44f34253f3c3 100644
--- a/packages/core/src/i18n/InternationalizationProvider.doc.mjs
+++ b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
@@ -118,6 +118,26 @@ export function AppI18n({children}: {children: ReactNode}) {
{children}
);
+}`,
+ },
+ {
+ label: 'Mirror the layout for right-to-left text',
+ code: `import type {ReactNode} from 'react';
+import {
+ InternationalizationProvider,
+ getLocaleDirection,
+} from '@astryxdesign/core/i18n';
+
+// Pass the same direction to the provider and to the element that holds the
+// content, so Astryx components and the page mirror together.
+export function AppI18n({children}: {children: ReactNode}) {
+ const locale = 'ar-SA';
+ const dir = getLocaleDirection(locale);
+ return (
+
+ {children}
+
+ );
}`,
},
{
@@ -136,6 +156,25 @@ export function AppI18n({children}: {children: ReactNode}) {
{children}
);
+}`,
+ },
+ {
+ label: 'Provide a local fallback catalog',
+ code: `import type {ReactNode} from 'react';
+import {
+ InternationalizationProvider,
+ type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
+import ptBR from './locales/pt-BR.json';
+
+const messages: MessagesByLocale = {'pt-BR': ptBR};
+
+export function AppI18n({children}: {children: ReactNode}) {
+ return (
+
+ {children}
+
+ );
}`,
},
{
@@ -153,15 +192,15 @@ export function AppI18n({children}: {children: ReactNode}) {
}`,
},
{
- label: 'Show Calendar and DateInput in the Japanese calendar',
+ label: 'Show Calendar and DateInput in another calendar',
code: `import {useState} from 'react';
import {InternationalizationProvider} from '@astryxdesign/core/i18n';
import {Calendar, type ISODateString} from '@astryxdesign/core/Calendar';
import {DateInput} from '@astryxdesign/core/DateInput';
import {VStack} from '@astryxdesign/core/Layout';
-// Japanese, Buddhist, and ROC dates need no Temporal, so they work in every
-// browser. The value stays a Gregorian ISO date.
+// Japanese, Buddhist, and Minguo calendar dates need no Temporal, so they work
+// in every browser. The value stays a Gregorian ISO date.
export function StartDate() {
const [value, setValue] = useState('2026-10-30');
return (
@@ -172,25 +211,6 @@ export function StartDate() {
);
-}`,
- },
- {
- label: 'Provide a local fallback catalog',
- code: `import type {ReactNode} from 'react';
-import {
- InternationalizationProvider,
- type MessagesByLocale,
-} from '@astryxdesign/core/i18n';
-import ptBR from './locales/pt-BR.json';
-
-const messages: MessagesByLocale = {'pt-BR': ptBR};
-
-export function AppI18n({children}: {children: ReactNode}) {
- return (
-
- {children}
-
- );
}`,
},
],