Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[feat] i18n: InternationalizationProvider, useTranslator, and Pagination migration (#3765)

nynexman4464acd4fe3728f0
diff --git a/.changeset/i18n-scaffold-and-pagination.md b/.changeset/i18n-scaffold-and-pagination.md
new file mode 100644
index 0000000000..cef028af34
--- /dev/null
+++ b/.changeset/i18n-scaffold-and-pagination.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Astryx components are now translatable. Wrap your app in `<InternationalizationProvider locale="...">` and pass one or more locale catalogs to render astryx UI in the language of your choice. Call `useTranslator()` inside your own components to translate your consumer strings against the active locale.
+
+Astryx ships an English catalog and BCP 47 regional fallback (e.g. `pt-BR` → `pt` → `en`), so consumers who never render a provider see today's English strings unchanged.
+
+Pagination is the first component wired up as part of this change. More components follow in subsequent releases.
+
+@nynexman4464
diff --git a/.gitignore b/.gitignore
index c505f37a08..a6813c5560 100644
--- a/.gitignore
+++ b/.gitignore
@@ -68,3 +68,6 @@ yarn.lock
.node-version
.tool-versions
mise.toml
+
+# Generated i18n artifacts (rebuilt from en.json)
+packages/core/locales/pseudo.json
diff --git a/internal/eslint-plugin-astryx/shared.js b/internal/eslint-plugin-astryx/shared.js
index 58f4a50c69..46ac1f3879 100644
--- a/internal/eslint-plugin-astryx/shared.js
+++ b/internal/eslint-plugin-astryx/shared.js
@@ -32,6 +32,7 @@ export const COMPONENT_RULE_ALLOWED = new Set([
'LayerProviderProps',
'LinkProviderProps',
'MediaThemeProps',
+ 'InternationalizationProviderProps',
// Hook return-value / editor-config prop bags — not DOM-component props
'OverlayContainerProps',
'PowerSearchEditorProps',
diff --git a/internal/test-utils/src/globalSetup.ts b/internal/test-utils/src/globalSetup.ts
new file mode 100644
index 0000000000..5ee55bcd1d
--- /dev/null
+++ b/internal/test-utils/src/globalSetup.ts
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file globalSetup.ts
+ * @input None (runs once, before the whole test suite)
+ * @output Side effect: regenerates packages/core/locales/pseudo.json
+ * @position Vitest globalSetup hook; keeps generated i18n artifacts fresh so
+ * tests can import them without a preceding build step.
+ *
+ * pseudo.json is git-ignored and derived from en.json. This setup runs the
+ * generator once per test suite so tests that import the pseudo catalog
+ * always have an up-to-date copy.
+ */
+
+import {execFileSync} from 'node:child_process';
+import {resolve, dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export default function setup() {
+ // internal/test-utils/src → repo root
+ const repoRoot = resolve(HERE, '..', '..', '..');
+ const script = resolve(
+ repoRoot,
+ 'packages',
+ 'core',
+ 'scripts',
+ 'build-pseudo-locale.mjs',
+ );
+ execFileSync('node', [script], {stdio: 'inherit'});
+}
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
new file mode 100644
index 0000000000..629c278aa7
--- /dev/null
+++ b/packages/core/locales/en.json
@@ -0,0 +1,38 @@
+{
+ "@astryx.pagination.label": {
+ "defaultMessage": "Pagination",
+ "description": "Aria label for the pagination navigation region."
+ },
+ "@astryx.pagination.previous": {
+ "defaultMessage": "Go to previous page",
+ "description": "Aria label for the previous-page button."
+ },
+ "@astryx.pagination.next": {
+ "defaultMessage": "Go to next page",
+ "description": "Aria label for the next-page button."
+ },
+ "@astryx.pagination.goToPage": {
+ "defaultMessage": "Go to page {page, number}",
+ "description": "Aria label for an individual page-number button. `page` is 1-based."
+ },
+ "@astryx.pagination.pageIndicators": {
+ "defaultMessage": "Page indicators",
+ "description": "Aria label for the dots-variant page-indicator group."
+ },
+ "@astryx.pagination.itemsPerPage": {
+ "defaultMessage": "Items per page",
+ "description": "Label for the page-size selector."
+ },
+ "@astryx.pagination.count": {
+ "defaultMessage": "{from, number}\u2013{to, number} of {total, number}",
+ "description": "Visible range-of-total text for the count variant. `from`/`to` are 1-based item indices."
+ },
+ "@astryx.pagination.pageOfTotal": {
+ "defaultMessage": "Page {current, number} of {total, number}",
+ "description": "Page-x-of-y text. Used as the visible compact-variant text and as the screen-reader announcement when total is known."
+ },
+ "@astryx.pagination.pageAnnounce": {
+ "defaultMessage": "Page {current, number}",
+ "description": "Screen-reader announcement when a page changes and total is unknown."
+ }
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index 0128f723d9..d39335a707 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -76,6 +76,7 @@
},
"./docs.mjs": "./docs.mjs",
"./groups.doc.mjs": "./groups.doc.mjs",
+ "./locales/*.json": "./locales/*.json",
"./AlertDialog": {
"source": "./src/AlertDialog/index.ts",
"types": "./dist/AlertDialog/index.d.ts",
@@ -576,6 +577,11 @@
"types": "./dist/hooks/index.d.ts",
"default": "./dist/hooks/index.js"
},
+ "./i18n": {
+ "source": "./src/i18n/index.ts",
+ "types": "./dist/i18n/index.d.ts",
+ "default": "./dist/i18n/index.js"
+ },
"./theme": {
"source": "./src/theme/index.ts",
"types": "./dist/theme/index.d.ts",
@@ -620,6 +626,7 @@
"files": [
"dist",
"src",
+ "locales",
"docs.mjs",
"groups.doc.mjs",
"README.md",
@@ -627,7 +634,8 @@
],
"scripts": {
"prepack": "pnpm build",
- "build": "rimraf dist && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs",
+ "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs",
+ "build:i18n": "node scripts/build-pseudo-locale.mjs",
"build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",
"build:css": "node ../../scripts/build-css.mjs",
"build:umd": "node ../../scripts/build-umd.mjs",
@@ -653,5 +661,8 @@
"@testing-library/jest-dom": "^6.6.0",
"@testing-library/react": "^16.3.2",
"rimraf": "^6.0.1"
+ },
+ "dependencies": {
+ "intl-messageformat": "^11.2.9"
}
}
diff --git a/packages/core/scripts/build-pseudo-locale.mjs b/packages/core/scripts/build-pseudo-locale.mjs
new file mode 100644
index 0000000000..32c5ee3f32
--- /dev/null
+++ b/packages/core/scripts/build-pseudo-locale.mjs
@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build-pseudo-locale.mjs
+ * @description Generates packages/core/locales/pseudo.json from en.json for
+ * dev/test use. Each defaultMessage is wrapped in ⟦...⟧ markers and its
+ * letters are replaced with accented forms so untranslated strings are
+ * obviously visible in the UI and narrow-column layout bugs surface.
+ *
+ * Placeholders like {name}, {count, plural, ...} are left INTACT so the
+ * ICU parser still works. Only literal letters are transformed.
+ *
+ * Usage:
+ * node packages/core/scripts/build-pseudo-locale.mjs
+ *
+ * Runs as part of the core build so pseudo.json stays in sync with en.json.
+ */
+
+import {readFileSync, writeFileSync} from 'node:fs';
+import {resolve, dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const EN_PATH = resolve(HERE, '..', 'locales', 'en.json');
+const PSEUDO_PATH = resolve(HERE, '..', 'locales', 'pseudo.json');
+
+const ACCENTED = {
+ a: 'à', b: 'ƀ', c: 'ç', d: 'ð', e: 'é', f: 'ƒ', g: 'ĝ', h: 'ĥ',
+ i: 'í', j: 'ĵ', k: 'ķ', l: 'ł', m: 'ɱ', n: 'ñ', o: 'ó', p: 'þ',
+ q: 'ɋ', r: 'ř', s: 'š', t: 'ţ', u: 'ú', v: 'ṽ', w: 'ŵ', x: 'ẋ',
+ y: 'ý', z: 'ž',
+ A: 'À', B: 'Ɓ', C: 'Ç', D: 'Ð', E: 'É', F: 'Ƒ', G: 'Ĝ', H: 'Ĥ',
+ I: 'Í', J: 'Ĵ', K: 'Ķ', L: 'Ł', M: 'Ṁ', N: 'Ñ', O: 'Ó', P: 'Þ',
+ Q: 'Ǫ', R: 'Ř', S: 'Š', T: 'Ţ', U: 'Ú', V: 'Ṽ', W: 'Ŵ', X: 'Ẋ',
+ Y: 'Ý', Z: 'Ž',
+};
+
+function pseudoTranslate(msg) {
+ let out = '';
+ let depth = 0;
+ for (const ch of msg) {
+ if (ch === '{') { depth++; out += ch; continue; }
+ if (ch === '}') { depth--; out += ch; continue; }
+ if (depth > 0) { out += ch; continue; }
+ out += ACCENTED[ch] ?? ch;
+ }
+ return `\u27E6${out}\u27E7`;
+}
+
+const en = JSON.parse(readFileSync(EN_PATH, 'utf8'));
+const pseudo = {};
+for (const [key, entry] of Object.entries(en)) {
+ pseudo[key] = {defaultMessage: pseudoTranslate(entry.defaultMessage)};
+}
+
+writeFileSync(PSEUDO_PATH, JSON.stringify(pseudo, null, 2) + '\n', 'utf8');
+console.log(`Built pseudo.json — ${Object.keys(pseudo).length} keys`);
diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index c82fbaf674..ed7a502835 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -39,6 +39,7 @@ import {useListFocus} from '../hooks/useListFocus';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n/useTranslator';
// =============================================================================
// Types
@@ -344,7 +345,7 @@ export function Pagination({
siblingCount = 1,
size = 'md',
isDisabled = false,
- label = 'Pagination',
+ label: labelFromProps,
'data-testid': testId,
xstyle,
className,
@@ -354,6 +355,14 @@ export function Pagination({
}: PaginationProps) {
const [, startTransition] = useTransition();
+ // Resolve system strings once per render. Prop overrides win.
+ const t = useTranslator();
+ const label = labelFromProps ?? t('@astryx.pagination.label');
+ const previousLabel = t('@astryx.pagination.previous');
+ const nextLabel = t('@astryx.pagination.next');
+ const pageIndicatorsLabel = t('@astryx.pagination.pageIndicators');
+ const itemsPerPageLabel = t('@astryx.pagination.itemsPerPage');
+
// pageSize is typed as number, so 0, NaN, and negatives are valid at the
// type level but yield Infinity/NaN page counts, and
// Array.from({length: Infinity}) crashes the dots variant. Coerce to a
@@ -418,8 +427,11 @@ export function Pagination({
onChange(newPage);
announce(
computedTotalPages != null
- ? `Page ${newPage} of ${computedTotalPages}`
- : `Page ${newPage}`,
+ ? t('@astryx.pagination.pageOfTotal', {
+ current: newPage,
+ total: computedTotalPages,
+ })
+ : t('@astryx.pagination.pageAnnounce', {current: newPage}),
);
startTransition(async () => {
setOptimisticPage(newPage);
@@ -511,8 +523,10 @@ export function Pagination({
return (
<Button
key={item}
- label={`Go to page ${item}`}
- aria-label={`Go to page ${item}`}
+ label={t('@astryx.pagination.goToPage', {page: item})}
+ aria-label={t('@astryx.pagination.goToPage', {
+ page: item,
+ })}
variant="ghost"
size={buttonSize}
onClick={() => handlePageChange(item)}
@@ -534,7 +548,11 @@ export function Pagination({
return (
<span {...stylex.props(styles.infoText)}>
<Text type="body" size="sm" color="secondary">
- {`${rangeStart}\u2013${rangeEnd} of ${totalItems}`}
+ {t('@astryx.pagination.count', {
+ from: rangeStart,
+ to: rangeEnd,
+ total: totalItems,
+ })}
</Text>
</span>
);
@@ -547,7 +565,10 @@ export function Pagination({
return (
<span {...stylex.props(styles.infoText)}>
<Text type="body" size="sm" color="secondary">
- {`Page ${optimisticPage} of ${computedTotalPages}`}
+ {t('@astryx.pagination.pageOfTotal', {
+ current: optimisticPage,
+ total: computedTotalPages,
+ })}
</Text>
</span>
);
@@ -563,7 +584,7 @@ export function Pagination({
ref={dotsListRef}
{...stylex.props(styles.dotsContainer)}
role="group"
- aria-label="Page indicators"
+ aria-label={pageIndicatorsLabel}
onKeyDown={handleDotsKeyDown}
onFocus={handleDotsFocus}>
{Array.from({length: computedTotalPages}, (_, i) => {
@@ -573,7 +594,9 @@ export function Pagination({
key={i + 1}
type="button"
data-page={i + 1}
- aria-label={`Go to page ${i + 1}`}
+ aria-label={t('@astryx.pagination.goToPage', {
+ page: i + 1,
+ })}
aria-current={isActive ? 'page' : undefined}
// The active dot is the single roving tab stop; useListFocus
// maintains it as focus and the active page move.
@@ -624,7 +647,7 @@ export function Pagination({
<div {...stylex.props(styles.pageSizeSelector)}>
<div {...stylex.props(styles.pageSizeSelectorControl)}>
<Selector
- label="Items per page"
+ label={itemsPerPageLabel}
isLabelHidden
options={pageSizeOptions.map(opt => String(opt))}
value={String(pageSize)}
@@ -637,7 +660,7 @@ export function Pagination({
)}
<div {...stylex.props(styles.controls)}>
<Button
- label="Go to previous page"
+ label={previousLabel}
variant="ghost"
size={buttonSize}
icon={<Icon icon="chevronLeft" size={isSm ? 'sm' : 'md'} />}
@@ -649,7 +672,7 @@ export function Pagination({
{renderIndicator()}
<Button
- label="Go to next page"
+ label={nextLabel}
variant="ghost"
size={buttonSize}
icon={<Icon icon="chevronRight" size={isSm ? 'sm' : 'md'} />}
diff --git a/packages/core/src/i18n/InternationalizationContext.ts b/packages/core/src/i18n/InternationalizationContext.ts
new file mode 100644
index 0000000000..9932bd8531
--- /dev/null
+++ b/packages/core/src/i18n/InternationalizationContext.ts
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InternationalizationContext.ts
+ * @input React createContext, i18n types
+ * @output Exports InternationalizationContext and InternationalizationContextValue
+ * @position Context definition for client-side locale + messages
+ *
+ * Separated from InternationalizationProvider.tsx so components can consume
+ * the context without pulling in the full provider implementation.
+ * Follows the LinkContext.ts / ThemeContext.ts pattern.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx
+ * - /packages/core/src/i18n/t.client.ts
+ * - /packages/core/src/i18n/index.ts
+ */
+
+import {createContext} from 'react';
+import type {Locale, MessagesByLocale, Overrides} from './types';
+
+export interface InternationalizationContextValue {
+ locale: Locale;
+ messages: MessagesByLocale;
+ overrides?: Overrides;
+}
+
+/**
+ * Default value falls through to the shipped en catalog in resolve().
+ * A consumer that doesn't render a provider still gets English defaults.
+ */
+export const InternationalizationContext =
+ createContext<InternationalizationContextValue>({
+ locale: 'en',
+ messages: {},
+ });
+InternationalizationContext.displayName = 'InternationalizationContext';
diff --git a/packages/core/src/i18n/InternationalizationProvider.doc.mjs b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
new file mode 100644
index 0000000000..da0c5e4c16
--- /dev/null
+++ b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'InternationalizationProvider',
+ displayName: 'Internationalization Provider',
+ group: 'Utilities',
+ category: 'Utility',
+ isHiddenFromOverview: true,
+ keywords: [
+ 'i18n',
+ 'internationalization',
+ 'localization',
+ 'locale',
+ 'translation',
+ 'translations',
+ 'provider',
+ 'language',
+ ],
+ usage: {
+ description:
+ "Wraps your app to set the active locale and (optionally) merge additional translation catalogs + per-locale overrides. Astryx components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.",
+ },
+ props: [
+ {
+ name: 'locale',
+ type: 'string',
+ required: true,
+ description:
+ 'BCP 47 language tag for the active locale (e.g. "en", "pt", "pt-BR", "zh-Hans"). Regional tags fall back to their base language, then to the shipped "en" catalog.',
+ },
+ {
+ name: 'messages',
+ type: 'MessagesByLocale',
+ required: false,
+ description:
+ 'Optional map of BCP 47 tag to translation catalog. The shipped "en" catalog is always available and does not need to be listed here.',
+ },
+ {
+ name: 'overrides',
+ type: 'Overrides',
+ required: false,
+ description:
+ 'Sparse per-locale key overrides applied on top of shipped defaults. Overrides are locale-keyed so a runtime locale swap picks up the correct set.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ required: true,
+ description: 'Content to render with the internationalization provider.',
+ },
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description:
+ 'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',
+ usage: {
+ description:
+ 'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',
+ },
+ propDescriptions: {
+ locale:
+ 'BCP 47 language tag (e.g. "en", "pt-BR"); regional tags fall back to base language then "en"',
+ messages:
+ 'map of BCP 47 tag to translation catalog; "en" is always available',
+ overrides:
+ 'sparse per-locale key overrides applied on top of shipped defaults',
+ },
+};
diff --git a/packages/core/src/i18n/InternationalizationProvider.tsx b/packages/core/src/i18n/InternationalizationProvider.tsx
new file mode 100644
index 0000000000..7005aa139c
--- /dev/null
+++ b/packages/core/src/i18n/InternationalizationProvider.tsx
@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InternationalizationProvider.tsx
+ * @input React, InternationalizationContext, i18n types
+ * @output Exports InternationalizationProvider component and props type
+ * @position Provider component for astryx i18n locale + messages
+ *
+ * Wraps a subtree with a locale and (optional) additional message catalogs +
+ * overrides. Astryx components inside the subtree resolve their strings via
+ * this context. If a consumer never renders a provider, astryx components
+ * still work — they use the shipped en catalog directly.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/index.ts
+ * - /packages/core/src/i18n/InternationalizationProvider.doc.mjs
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+import type {Locale, MessagesByLocale, Overrides} from './types';
+
+export interface InternationalizationProviderProps {
+ /**
+ * BCP 47 language tag. Examples: `'en'`, `'pt'`, `'pt-BR'`, `'zh-Hans'`.
+ *
+ * Regional tags are respected — resolving a message walks the tag from
+ * most-specific to least-specific (`pt-BR` → `pt`), then falls back to
+ * the shipped `en` catalog.
+ */
+ locale: Locale;
+ /**
+ * Additional shipped catalogs to make available for the selected locale.
+ * `en` is bundled with astryx and never needs to be listed here.
+ *
+ * @example
+ * ```
+ * import {fr} from '@astryxdesign/core/locales/fr.json';
+ * <InternationalizationProvider locale="fr" messages={{fr}}>
+ * ```
+ */
+ messages?: MessagesByLocale;
+ /**
+ * Sparse per-locale overrides applied on top of shipped defaults.
+ * Only the keys you want to override need to be listed.
+ *
+ * @example
+ * ```
+ * <InternationalizationProvider
+ * locale="fr"
+ * overrides={{fr: {'@astryx.pagination.next': 'Suivant'}}}
+ * >
+ * ```
+ */
+ overrides?: Overrides;
+ children: ReactNode;
+}
+
+/**
+ * Provides locale + additional messages + overrides to all astryx
+ * components in the subtree.
+ */
+export function InternationalizationProvider({
+ locale,
+ messages,
+ overrides,
+ children,
+}: InternationalizationProviderProps) {
+ const value = useMemo(
+ () => ({locale, messages: messages ?? {}, overrides}),
+ [locale, messages, overrides],
+ );
+ return (
+ <InternationalizationContext value={value}>
+ {children}
+ </InternationalizationContext>
+ );
+}
+
+InternationalizationProvider.displayName = 'InternationalizationProvider';
diff --git a/packages/core/src/i18n/__tests__/e2e-pagination.test.tsx b/packages/core/src/i18n/__tests__/e2e-pagination.test.tsx
new file mode 100644
index 0000000000..c812ab54be
--- /dev/null
+++ b/packages/core/src/i18n/__tests__/e2e-pagination.test.tsx
@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file e2e-pagination.test.tsx
+ * @input packages/core/src/Pagination, packages/core/src/i18n
+ * @output End-to-end tests proving the i18n framework actually swaps
+ * strings in real component output.
+ * @position Integration test: real component + real provider + real catalog.
+ * Not a unit test of resolve() — that's covered in resolve.test.ts.
+ *
+ * These assertions render <Pagination> and check that:
+ * 1. Default (no provider): English strings appear
+ * 2. With pseudo locale: accented+bracketed strings appear
+ * 3. With sparse override: only the overridden key changes
+ * 4. Regional locale fallback: pt-BR falls back to pt then en
+ * 5. Number formatting respects the locale (en-US vs de-DE separators)
+ */
+
+import {describe, test, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Pagination} from '../../Pagination';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+import pseudoCatalog from '../../../locales/pseudo.json';
+
+describe('Pagination × i18n — end to end', () => {
+ test('renders English strings by default (no provider)', () => {
+ render(
+ <Pagination
+ page={2}
+ totalItems={100}
+ pageSize={10}
+ onChange={() => {}}
+ variant="count"
+ />,
+ );
+
+ // The nav landmark uses the default label "Pagination"
+ expect(
+ screen.getByRole('navigation', {name: 'Pagination'}),
+ ).toBeInTheDocument();
+
+ // Prev/Next buttons carry English aria-labels
+ expect(
+ screen.getByRole('button', {name: 'Go to previous page'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to next page'}),
+ ).toBeInTheDocument();
+
+ // The visible count text is "11–20 of 100"
+ expect(screen.getByText(/11.20 of 100/)).toBeInTheDocument();
+ });
+
+ test('renders pseudo strings when provider locale is pseudo', () => {
+ render(
+ <InternationalizationProvider
+ locale="pseudo"
+ messages={{pseudo: pseudoCatalog}}>
+ <Pagination
+ page={2}
+ totalItems={100}
+ pageSize={10}
+ onChange={() => {}}
+ variant="count"
+ />
+ </InternationalizationProvider>,
+ );
+
+ // Nav landmark shows pseudo-translated label
+ expect(
+ screen.getByRole('navigation', {name: /Þàĝíñàţíóñ/}),
+ ).toBeInTheDocument();
+
+ // Prev/Next aria-labels are pseudo-translated
+ expect(
+ screen.getByRole('button', {name: /Ĝó ţó þřéṽíóúš/}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: /Ĝó ţó ñéẋţ/}),
+ ).toBeInTheDocument();
+
+ // Visible count is pseudo-wrapped; numbers still format
+ expect(screen.getByText(/⟦11.20 óƒ 100⟧/)).toBeInTheDocument();
+ });
+
+ test('sparse override changes only the overridden key', () => {
+ render(
+ <InternationalizationProvider
+ locale="fr"
+ overrides={{
+ fr: {'@astryx.pagination.next': 'Suivant'},
+ }}>
+ <Pagination
+ page={2}
+ totalItems={100}
+ pageSize={10}
+ onChange={() => {}}
+ />
+ </InternationalizationProvider>,
+ );
+
+ // Overridden key: French
+ expect(screen.getByRole('button', {name: 'Suivant'})).toBeInTheDocument();
+
+ // NON-overridden keys fall through to English (fr has no other catalog)
+ expect(
+ screen.getByRole('navigation', {name: 'Pagination'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to previous page'}),
+ ).toBeInTheDocument();
+ });
+
+ test('regional locale (pt-BR) falls back to base language (pt)', () => {
+ // pt-BR has one key, pt has another, en fills in the rest.
+ // Tests the resolveLocaleChain walking through resolve() end to end.
+ render(
+ <InternationalizationProvider
+ locale="pt-BR"
+ messages={{
+ 'pt-BR': {
+ '@astryx.pagination.next': {defaultMessage: 'Próxima (BR)'},
+ },
+ pt: {
+ '@astryx.pagination.previous': {defaultMessage: 'Anterior'},
+ },
+ }}>
+ <Pagination
+ page={2}
+ totalItems={100}
+ pageSize={10}
+ onChange={() => {}}
+ />
+ </InternationalizationProvider>,
+ );
+
+ // next: from pt-BR
+ expect(
+ screen.getByRole('button', {name: 'Próxima (BR)'}),
+ ).toBeInTheDocument();
+
+ // previous: from pt (fallback pt-BR → pt)
+ expect(screen.getByRole('button', {name: 'Anterior'})).toBeInTheDocument();
+
+ // label: neither pt-BR nor pt has it — falls back to en
+ expect(
+ screen.getByRole('navigation', {name: 'Pagination'}),
+ ).toBeInTheDocument();
+ });
+
+ test('ICU number formatting respects the locale', () => {
+ // In de-DE, 1000 formats with "." as the thousands separator.
+ render(
+ <InternationalizationProvider locale="de-DE">
+ <Pagination
+ page={2}
+ totalItems={10000}
+ pageSize={10}
+ onChange={() => {}}
+ variant="count"
+ />
+ </InternationalizationProvider>,
+ );
+
+ // We didn't provide a de-DE catalog — the string is en's pattern but
+ // numbers format under the de-DE locale, so "10000" becomes "10.000".
+ // Text is: "11–20 of 10.000"
+ // The dash between 11 and 20 is unicode en-dash (\u2013), match loosely
+ // by asserting the presence of the German-formatted 10.000.
+ expect(screen.getByText(/10\.000/)).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/i18n/__tests__/resolve.test.ts b/packages/core/src/i18n/__tests__/resolve.test.ts
new file mode 100644
index 0000000000..76507d3c0a
--- /dev/null
+++ b/packages/core/src/i18n/__tests__/resolve.test.ts
@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resolve.test.ts
+ * @input packages/core/src/i18n/resolve.ts
+ * @output Unit tests for the shared i18n lookup + format core
+ * @position Colocated tests; targets locale-chain fallback, ICU formatting,
+ * overrides, and missing-key behavior.
+ */
+
+import {describe, expect, test, beforeEach, vi} from 'vitest';
+import {__resetForTests, resolve, resolveLocaleChain} from '../resolve';
+import type {Catalog, MessagesByLocale, Overrides} from '../types';
+
+// Reset caches between tests so warn-once and formatter cache don't bleed.
+beforeEach(() => {
+ __resetForTests();
+});
+
+describe('resolveLocaleChain', () => {
+ test('single-part tag returns single-item chain', () => {
+ expect(resolveLocaleChain('en')).toEqual(['en']);
+ });
+
+ test('regional tag walks to base language', () => {
+ expect(resolveLocaleChain('pt-BR')).toEqual(['pt-BR', 'pt']);
+ });
+
+ test('script-tagged locale walks to script and then base', () => {
+ expect(resolveLocaleChain('zh-Hans-CN')).toEqual([
+ 'zh-Hans-CN',
+ 'zh-Hans',
+ 'zh',
+ ]);
+ });
+
+ test('canonicalizes casing via Intl.Locale', () => {
+ // Consumers who pass "en-us" (lowercase region) should get the canonical
+ // BCP 47 form back so lookups match spec-canonical catalog keys.
+ expect(resolveLocaleChain('en-us')).toEqual(['en-US', 'en']);
+ expect(resolveLocaleChain('PT-br')).toEqual(['pt-BR', 'pt']);
+ });
+
+ test('malformed input falls back to the raw string chain', () => {
+ // Intl.Locale throws on invalid input; we don't want the whole render to
+ // die because a consumer passed a bad tag.
+ expect(resolveLocaleChain('not_a_locale')).toEqual(['not_a_locale']);
+ });
+});
+
+describe('resolve — basic lookup', () => {
+ test('falls back to shipped en catalog when locale is en and no messages passed', () => {
+ // The shipped en.json is imported at module load; Pagination keys should
+ // resolve. This asserts the module wiring works end-to-end.
+ const out = resolve(
+ '@astryx.pagination.next',
+ undefined,
+ 'en',
+ {},
+ undefined,
+ );
+ expect(out).toBe('Go to next page');
+ });
+
+ test('returns the key itself and warns for unknown key', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const out = resolve(
+ '@astryx.does.not.exist',
+ undefined,
+ 'en',
+ {},
+ undefined,
+ );
+ expect(out).toBe('@astryx.does.not.exist');
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('missing key'));
+ warn.mockRestore();
+ });
+});
+
+describe('resolve — provider messages', () => {
+ const catalog: Catalog = {
+ '@astryx.pagination.next': {defaultMessage: 'Suivant'},
+ };
+ const messages: MessagesByLocale = {fr: catalog};
+
+ test('uses provider messages for the current locale', () => {
+ const out = resolve(
+ '@astryx.pagination.next',
+ undefined,
+ 'fr',
+ messages,
+ undefined,
+ );
+ expect(out).toBe('Suivant');
+ });
+
+ test('falls back to en for keys not in the provider catalog, silently', () => {
+ // pagination.previous is only in en; fr catalog has only .next.
+ // Missing translations for a locale are expected during rollout — the
+ // fallback should be silent (matches i18next / FormatJS default). We
+ // reserve console.warn for real bugs (key missing even from en).
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const out = resolve(
+ '@astryx.pagination.previous',
+ undefined,
+ 'fr',
+ messages,
+ undefined,
+ );
+ expect(out).toBe('Go to previous page');
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
+ });
+});
+
+describe('resolve — locale-chain fallback (regional → language)', () => {
+ const messages: MessagesByLocale = {
+ 'pt-BR': {
+ '@astryx.pagination.next': {defaultMessage: 'Próxima (BR)'},
+ },
+ pt: {
+ '@astryx.pagination.next': {defaultMessage: 'Próxima'},
+ '@astryx.pagination.previous': {defaultMessage: 'Anterior'},
+ },
+ };
+
+ test('exact regional match wins', () => {
+ const out = resolve(
+ '@astryx.pagination.next',
+ undefined,
+ 'pt-BR',
+ messages,
+ undefined,
+ );
+ expect(out).toBe('Próxima (BR)');
+ });
+
+ test('falls back to base language when regional entry missing', () => {
+ // pt-BR catalog has no .previous — should walk pt-BR → pt
+ const out = resolve(
+ '@astryx.pagination.previous',
+ undefined,
+ 'pt-BR',
+ messages,
+ undefined,
+ );
+ expect(out).toBe('Anterior');
+ });
+
+ test('falls back to en when neither regional nor base has the key', () => {
+ // pt-BR nor pt has .label — walk to en
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const out = resolve(
+ '@astryx.pagination.label',
+ undefined,
+ 'pt-BR',
+ messages,
+ undefined,
+ );
+ expect(out).toBe('Pagination');
+ warn.mockRestore();
+ });
+});
+
+describe('resolve — overrides', () => {
+ test('per-locale override wins over shipped catalog', () => {
+ const messages: MessagesByLocale = {
+ fr: {'@astryx.pagination.next': {defaultMessage: 'Suivant'}},
+ };
+ const overrides: Overrides = {
+ fr: {'@astryx.pagination.next': 'Suiv.'},
+ };
+ const out = resolve(
+ '@astryx.pagination.next',
+ undefined,
+ 'fr',
+ messages,
+ overrides,
+ );
+ expect(out).toBe('Suiv.');
+ });
+
+ test('overrides respect the locale chain (pt-BR → pt)', () => {
+ // Override defined at pt level, current locale is pt-BR
+ const overrides: Overrides = {
+ pt: {'@astryx.pagination.next': 'Próxima (pt override)'},
+ };
+ const out = resolve(
+ '@astryx.pagination.next',
+ undefined,
+ 'pt-BR',
+ {},
+ overrides,
+ );
+ expect(out).toBe('Próxima (pt override)');
+ });
+
+ test('override for a different locale does not apply', () => {
+ const overrides: Overrides = {
+ es: {'@astryx.pagination.next': 'Siguiente'},
+ };
+ const out = resolve(
+ '@astryx.pagination.next',
+ undefined,
+ 'fr',
+ {},
+ overrides,
+ );
+ // Should fall through to en since fr has no messages and es override doesn't apply
+ expect(out).toBe('Go to next page');
+ });
+});
+
+describe('resolve — ICU MessageFormat', () => {
+ test('interpolates simple named placeholders', () => {
+ const out = resolve(
+ '@astryx.pagination.goToPage',
+ {page: 5},
+ 'en',
+ {},
+ undefined,
+ );
+ expect(out).toContain('5');
+ expect(out).toMatch(/Go to page/);
+ });
+
+ test('formats numbers using Intl.NumberFormat for the locale', () => {
+ // Pagination.count uses {from, number}, {to, number}, {total, number}
+ // In en-US, 1000 formats as "1,000"
+ const out = resolve(
+ '@astryx.pagination.count',
+ {from: 1, to: 10, total: 1000},
+ 'en-US',
+ {},
+ undefined,
+ );
+ expect(out).toContain('1,000');
+ });
+
+ test('formats numbers for locales with different separators', () => {
+ // In de-DE, 1000 formats as "1.000"
+ const out = resolve(
+ '@astryx.pagination.count',
+ {from: 1, to: 10, total: 1000},
+ 'de-DE',
+ {},
+ undefined,
+ );
+ // We don't have a de catalog so falls back to en's PATTERN, but the
+ // number formatting uses the locale passed to IntlMessageFormat.
+ expect(out).toContain('1.000');
+ });
+
+ test('handles plural forms with ICU {n, plural, one {} other {}} pattern', () => {
+ const catalog: Catalog = {
+ 'test.items': {
+ defaultMessage:
+ '{count, plural, =0 {no items} one {# item} other {# items}}',
+ },
+ };
+ const messages = {en: catalog};
+
+ expect(resolve('test.items', {count: 0}, 'en', messages, undefined)).toBe(
+ 'no items',
+ );
+ expect(resolve('test.items', {count: 1}, 'en', messages, undefined)).toBe(
+ '1 item',
+ );
+ expect(resolve('test.items', {count: 5}, 'en', messages, undefined)).toBe(
+ '5 items',
+ );
+ });
+});
+
+describe('resolve — warn-once behavior', () => {
+ test('duplicate missing-key warnings are suppressed', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ resolve('@astryx.does.not.exist', undefined, 'en', {}, undefined);
+ resolve('@astryx.does.not.exist', undefined, 'en', {}, undefined);
+ resolve('@astryx.does.not.exist', undefined, 'en', {}, undefined);
+ expect(warn).toHaveBeenCalledTimes(1);
+ warn.mockRestore();
+ });
+});
diff --git a/packages/core/src/i18n/index.ts b/packages/core/src/i18n/index.ts
new file mode 100644
index 0000000000..9071978163
--- /dev/null
+++ b/packages/core/src/i18n/index.ts
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Imports from InternationalizationProvider, InternationalizationContext,
+ * useTranslator, translator, types
+ * @output Public surface for the i18n subpackage
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * The public API is deliberately small:
+ * - InternationalizationProvider — provider component
+ * - useTranslator — hook returning a translator function
+ * - Translator — interface for consumer-injected runtimes
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/index.ts
+ */
+
+export {InternationalizationProvider} from './InternationalizationProvider';
+export type {InternationalizationProviderProps} from './InternationalizationProvider';
+export {InternationalizationContext} from './InternationalizationContext';
+export type {InternationalizationContextValue} from './InternationalizationContext';
+export {useTranslator} from './useTranslator';
+export type {TranslatorFn} from './useTranslator';
+export type {Translator} from './translator';
+export type {
+ Locale,
+ Catalog,
+ MessageEntry,
+ MessagesByLocale,
+ Overrides,
+} from './types';
diff --git a/packages/core/src/i18n/resolve.ts b/packages/core/src/i18n/resolve.ts
new file mode 100644
index 0000000000..52e5ea3821
--- /dev/null
+++ b/packages/core/src/i18n/resolve.ts
@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resolve.ts
+ * @input Key + values + locale + catalog + overrides
+ * @output Formatted message string
+ * @position Shared lookup + ICU formatting core, used by useTranslator().
+ *
+ * Lookup order:
+ * 1. Per-locale override for the exact locale
+ * 2. Per-locale override for a parent locale (pt-BR → pt)
+ * 3. Shipped catalog entry for the exact locale
+ * 4. Shipped catalog entry for a parent locale (pt-BR → pt)
+ * 5. Shipped en catalog (the source of truth, always present)
+ * 6. The key itself (dev-visible fallback, warns once)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/useTranslator.ts
+ * - /packages/core/src/i18n/__tests__/resolve.test.ts
+ */
+
+import IntlMessageFormat from 'intl-messageformat';
+import type {Catalog, Locale, MessagesByLocale, Overrides} from './types';
+import enSource from '../../locales/en.json' with {type: 'json'};
+
+const EN_CATALOG = enSource as Catalog;
+
+/**
+ * Cache of parsed ICU MessageFormat objects keyed by `${locale}::${message}`.
+ * IntlMessageFormat parsing is non-trivial; caching avoids reparsing on every
+ * render. The cache is unbounded in principle but bounded in practice by the
+ * static set of astryx keys.
+ */
+const formatterCache = new Map<string, IntlMessageFormat>();
+
+function getFormatter(message: string, locale: Locale): IntlMessageFormat {
+ const cacheKey = `${locale}::${message}`;
+ let f = formatterCache.get(cacheKey);
+ if (f === undefined) {
+ f = new IntlMessageFormat(message, locale);
+ formatterCache.set(cacheKey, f);
+ }
+ return f;
+}
+
+/**
+ * Walk a BCP 47 tag from most-specific to least-specific.
+ * Input is canonicalized via `Intl.Locale.baseName` so `pt-br` and `PT-BR`
+ * both produce `['pt-BR', 'pt']`.
+ *
+ * Examples:
+ * 'pt-BR' → ['pt-BR', 'pt']
+ * 'zh-Hans-CN' → ['zh-Hans-CN', 'zh-Hans', 'zh']
+ * 'en' → ['en']
+ *
+ * `en` is intentionally NOT appended here — the caller falls back to the
+ * shipped en catalog separately as the final source-of-truth.
+ */
+export function resolveLocaleChain(locale: Locale): Locale[] {
+ let canonical: string;
+ try {
+ canonical = new Intl.Locale(locale).baseName;
+ } catch {
+ // Malformed input — fall back to the raw string so callers still get a chain.
+ canonical = locale;
+ }
+ const parts = canonical.split('-');
+ const chain: Locale[] = [];
+ for (let i = parts.length; i > 0; i--) {
+ chain.push(parts.slice(0, i).join('-'));
+ }
+ return chain;
+}
+
+/**
+ * Missing-key warn-once tracking. Fires ONLY when a key is missing from
+ * every source including the shipped `en` catalog — that's a real bug
+ * (typo, stale catalog, deleted key). Fallback to `en` from a non-en
+ * locale is expected and silent, matching the FormatJS / i18next default
+ * of not spamming the console when a translation simply hasn't been
+ * written yet.
+ */
+const warnedMissing = new Set<string>();
+
+function warnOnce(bucket: Set<string>, key: string, message: string): void {
+ if (!bucket.has(key)) {
+ bucket.add(key);
+ console.warn(message);
+ }
+}
+
+function lookup(
+ key: string,
+ locale: Locale,
+ messages: MessagesByLocale,
+ overrides: Overrides | undefined,
+): string | null {
+ const chain = resolveLocaleChain(locale);
+
+ // 1 + 2. Overrides (most specific to least specific in the chain)
+ if (overrides !== undefined) {
+ for (const tag of chain) {
+ const value = overrides[tag]?.[key];
+ if (value !== undefined) {
+ return value;
+ }
+ }
+ }
+
+ // 3 + 4. Shipped catalogs (most specific to least specific)
+ for (const tag of chain) {
+ const entry = messages[tag]?.[key];
+ if (entry !== undefined) {
+ return entry.defaultMessage;
+ }
+ }
+
+ // 5. Shipped en catalog — always present
+ const enEntry = EN_CATALOG[key];
+ if (enEntry !== undefined) {
+ return enEntry.defaultMessage;
+ }
+
+ // 6. Nothing found
+ return null;
+}
+
+export function resolve(
+ key: string,
+ values: Record<string, unknown> | undefined,
+ locale: Locale,
+ messages: MessagesByLocale,
+ overrides: Overrides | undefined,
+): string {
+ const result = lookup(key, locale, messages, overrides);
+
+ if (result === null) {
+ warnOnce(
+ warnedMissing,
+ `${locale}::${key}`,
+ `[astryx-i18n] missing key: ${key} (locale: ${locale})`,
+ );
+ return key;
+ }
+
+ if (values === undefined) {
+ // Static string — skip the parser entirely for the common case
+ return result;
+ }
+
+ const formatted = getFormatter(result, locale).format(values);
+ // IntlMessageFormat.format returns string | (string | React elements) — we
+ // only ever pass string values so it will be a string; assert for the type
+ // system.
+ return formatted as string;
+}
+
+/**
+ * Reset internal caches. Test-only.
+ * @internal
+ */
+export function __resetForTests(): void {
+ formatterCache.clear();
+ warnedMissing.clear();
+}
diff --git a/packages/core/src/i18n/translator.ts b/packages/core/src/i18n/translator.ts
new file mode 100644
index 0000000000..5bd549ad53
--- /dev/null
+++ b/packages/core/src/i18n/translator.ts
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file translator.ts
+ * @input Translator interface for consumer i18n runtime injection
+ * @output Type surface for pluggable translators
+ * @position Public API for i18n adapter integration
+ *
+ * Consumers who already run an i18n runtime (react-intl, Lingui, i18next, etc.)
+ * can inject their own Translator instead of using the default provider. The
+ * interface is deliberately small so any real i18n library can satisfy it in a
+ * few lines.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/index.ts
+ */
+
+/**
+ * A Translator formats ICU MessageFormat strings for a given locale.
+ * Consumers can supply their own to reuse their existing i18n runtime.
+ */
+export interface Translator {
+ /**
+ * Format an ICU MessageFormat message with values in the given locale.
+ */
+ format(
+ message: string,
+ values?: Record<string, unknown>,
+ locale?: string,
+ ): string;
+}
diff --git a/packages/core/src/i18n/types.ts b/packages/core/src/i18n/types.ts
new file mode 100644
index 0000000000..6da7726e50
--- /dev/null
+++ b/packages/core/src/i18n/types.ts
@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @input None
+ * @output Shared types for the i18n subpackage
+ * @position Type-only module; used across client + server t() implementations
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx
+ * - /packages/core/src/i18n/serverStore.ts
+ * - /packages/core/src/i18n/resolve.ts
+ */
+
+/**
+ * A BCP 47 language tag. Examples: `'en'`, `'pt'`, `'pt-BR'`, `'zh-Hans'`.
+ *
+ * Regional tags are meaningful — `pt-BR` and `pt` are different catalogs.
+ * When resolving a message, the runtime walks the tag from most-specific
+ * to least-specific and falls back to `en` if nothing matches
+ * (see `resolveLocaleChain` in `resolve.ts`).
+ */
+export type Locale = string;
+
+/**
+ * A single entry in a translation catalog. The `defaultMessage` is an ICU
+ * MessageFormat string; `description` is optional context for translators
+ * (surfaced by Crowdin's `react_intl` file type parser).
+ */
+export interface MessageEntry {
+ defaultMessage: string;
+ description?: string;
+}
+
+/**
+ * A translation catalog — a map of stable message keys to entries.
+ * Astryx's own keys are namespaced under `@astryx.<component>.<name>`.
+ */
+export type Catalog = Record<string, MessageEntry>;
+
+/**
+ * A map of BCP 47 tags to catalogs. Passed as `messages` on
+ * `<InternationalizationProvider>`.
+ */
+export type MessagesByLocale = Record<Locale, Catalog>;
+
+/**
+ * Sparse per-locale overrides applied on top of the shipped defaults.
+ * Only the keys the consumer cares to override need to be listed.
+ * Overrides are locale-keyed so a runtime locale swap picks up the right ones.
+ */
+export type Overrides = Partial<Record<Locale, Record<string, string>>>;
diff --git a/packages/core/src/i18n/useTranslator.doc.mjs b/packages/core/src/i18n/useTranslator.doc.mjs
new file mode 100644
index 0000000000..a1d6496c1e
--- /dev/null
+++ b/packages/core/src/i18n/useTranslator.doc.mjs
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+ name: 'useTranslator',
+ displayName: 'useTranslator',
+ group: 'Utilities',
+ keywords: [
+ 'i18n',
+ 'internationalization',
+ 'localization',
+ 'translation',
+ 'translate',
+ 'locale',
+ 'hook',
+ ],
+ params: [],
+ returns: [
+ {
+ name: 'value',
+ type: '(key: string, values?: Record<string, string | number | Date>) => string',
+ description:
+ 'A stable translator function bound to the current InternationalizationProvider context. Call it with a message key and optional ICU MessageFormat values to get the formatted string in the active locale. Safe to use in render, event handlers, effects, or any code that runs during the parent component\'s lifecycle.',
+ },
+ ],
+ usage: {
+ description:
+ 'Returns a translator function that resolves keys against the current locale, provider overrides, and the shipped English fallback catalog. Call inside a component; the returned function can be used anywhere within that component\'s scope.',
+ },
+ relatedComponents: ['InternationalizationProvider'],
+ importPath: '@astryxdesign/core',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ 'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',
+ usage: {
+ description:
+ 'Returns a translator function that resolves keys against the current locale, provider overrides, and the shipped English fallback catalog.',
+ },
+};
diff --git a/packages/core/src/i18n/useTranslator.ts b/packages/core/src/i18n/useTranslator.ts
new file mode 100644
index 0000000000..86a3960be9
--- /dev/null
+++ b/packages/core/src/i18n/useTranslator.ts
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTranslator.ts
+ * @input InternationalizationContext (via use())
+ * @output Exports useTranslator hook returning a stable translator function
+ * @position Client-side hook for translating outside of render (event handlers,
+ * effects, non-component code) while still resolving against the current
+ * provider's locale.
+ *
+ * Prefer `t()` for translations at the callsite during render. When you need
+ * to translate inside an event handler or effect, capture a translator during
+ * render via useTranslator() and call it later.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/index.ts
+ * - /packages/core/src/i18n/t.client.ts
+ */
+
+import {use, useCallback} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+import {resolve} from './resolve';
+
+export type TranslatorFn = (
+ key: string,
+ values?: Record<string, unknown>,
+) => string;
+
+/**
+ * Returns a translator function bound to the current provider's locale.
+ * Safe to call from event handlers and effects.
+ *
+ * @example
+ * ```
+ * function MyComponent() {
+ * const translate = useTranslator();
+ * const onClick = () => announce(translate('@astryx.pagination.pageAnnounce', {current: 1}));
+ * }
+ * ```
+ */
+export function useTranslator(): TranslatorFn {
+ const ctx = use(InternationalizationContext);
+ return useCallback(
+ (key: string, values?: Record<string, unknown>) =>
+ resolve(key, values, ctx.locale, ctx.messages, ctx.overrides),
+ [ctx.locale, ctx.messages, ctx.overrides],
+ );
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index a6a01ca70b..55ff690722 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -170,6 +170,9 @@ export * from './utils';
// Theme
export * from './theme';
+// Internationalization
+export * from './i18n';
+
// Doc types — for external library authors writing .doc.mjs files
export type {
ComponentDoc,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ac519770d..91665bff4f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -38,7 +38,7 @@ importers:
version: 2.31.0(@types/[email protected])
'@eslint-react/eslint-plugin':
specifier: ^5.10.4
'@eslint/js':
specifier: ^10.0.1
@@ -62,7 +62,7 @@ importers:
'@vitest/coverage-v8':
specifier: ^4.1.9
- version: 4.1.9([email protected])
+ version: 4.1.10([email protected])
dom-accessibility-api:
specifier: ^0.6.3
version: 0.6.3
@@ -113,7 +113,7 @@ importers:
vitest:
specifier: ^4.1.9
apps/docsite:
dependencies:
@@ -219,7 +219,7 @@ importers:
version: 6.0.3
vitest:
specifier: ^4.1.9
apps/sandbox:
dependencies:
@@ -574,6 +574,9 @@ importers:
'@stylexjs/stylex':
specifier: ^0.19.0
version: 0.19.0
+ intl-messageformat:
+ specifier: ^11.2.9
+ version: 11.2.9
react:
specifier: '>=19.0.0'
version: 19.2.7
@@ -1397,50 +1400,50 @@ packages:
resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-FcxjL+TjzJeH+FnHRjahLEh5OccKIbPQwujxzribXMkkuHYOI44sLXtcOhslERiSU8DikOdnZzBNrhiujW9zwQ==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-/3/tgJOtS+Nor7SS6SWBuwcerlvOlgDcb2JKIghqBVNbbFRQMfH5uW4QKx6WmJmuhm5gesTHNwSdKoYdLtbCtQ==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-bxBgTtAx0VbZSWUP+TKqw80Z2vBX9aQ0v5XDOvx4juIgy9gIfND4DqFo6CIJ4SkmH0ZdzqiCBwmhbETHgXumnQ==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-boyE28fbCZohL86bRplMsbJP4xkxZNbgo4RMCB56saBQWefEs7eqSkQLIJexMJr48EzN4sZ2+faYRpCohyDNOA==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-5+bJsrBkXHarZBrSk9DBwRtbWXwW8GmXt2fYCNrJrp2hWtN2nzd9vI+9dkgQV1Pr1Jth5MoEJq4YRGbTL8bsBw==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-xUnJjEEp5Z+P0HkXrGvErRNcMgcZlOi+89QAxsBw1JfWJt7vb+cLdsgUnylYM2L4+qPtIEaQO6JoyOquo8GPsg==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-/PHUvYVpRZRvWVT15HySdCySxZ2d6KmlBV4VomhmQocvb6n/haRJ4SVTqSy0I+CV327TBFnaHw1hUdMw7zROxw==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-E6J+umqSshxyJ4h8wevlGHWZlCffQsZAWJe3AAhtxTcvrOf2RH6Om+3QGhUz1HeOCk1hBlt0Ceklg8cPscGwNg==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-XK374cpduryK3+/zDCWegF+c1ilLF8T0a1lCC5J9Z/56uGf7n/bEASyTyBLsnkJlxX/8+b9sYXT+lqnOAAyoNg==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-Zu2U6sAMPlgxfXukBpKbS7oOb9xcFm4KZVZo48He+p/gapiyZIGOapWUf/R6ehmD5t9MtqWWZ6kH4UnAJ2HD+Q==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-gPWtJ4IYAwa3rAyRBh0Lkw6dWXSPLCzlQVttMyb4JFFcIYSnlPkiHv/MIpa24F8Mp40AapqOaX57JXJSgZ3eSQ==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-lXOx688k7eZjRfi+Ig3NqNmNujnGWL6nrTyc0L/Id9pmWpkF8zU8nCzeEVLw/+OZb7zB703qEkdIvatdOI+aNQ==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- '@eslint-react/[email protected]':
- resolution: {integrity: sha512-fXqXn6tlvp/eJFDuqhWilaMifwLDcY1fMT9/q5PZJb7N9Row7oJ6tHy9zPTBhle0jAU+QprhK0irHGTlUqlN8Q==}
+ '@eslint-react/[email protected]':
+ resolution: {integrity: sha512-Y+l5CSkrvLxB/K5wgzfq89piBwfVwcSAClz80+X0jtE4jq93tZsSk0k4UA4Bx5FNtPgMro1vvaAOpXER4RYbpQ==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
@@ -1499,6 +1502,15 @@ packages:
'@floating-ui/[email protected]':
resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+ '@formatjs/[email protected]':
+ resolution: {integrity: sha512-H5aexk1Le7T9TPmscacZ+1pR6CTa2n1wq+HDVGXhH8TzUlQQpeXzZs91dRtmFHrbeNbjPFPfQujUqm7MHgVoXQ==}
+
+ '@formatjs/[email protected]':
+ resolution: {integrity: sha512-YyzzxVgYJ8DELmmkhn0Yr0rUj0dTJFf9Jp628K3S0ysInBWxLVDOS8i3RP91cCp4DMK4WYb4cVMhWA9i4knSJg==}
+
+ '@formatjs/[email protected]':
+ resolution: {integrity: sha512-XuSva+8ZGawk8VnD5VD6UeH8KarQ/Z022zgjHDoHmlNiAewstXuuzXc0Hk5pGFSdG+nNw5bfJKXqj1ZXHn9yUA==}
+
'@heroicons/[email protected]':
resolution: {integrity: sha512-LMcepvRaS9LYHJGsF0zzmgKCUim/X3N/DQKc4jepAXJ7l8QxJ1PmxJzqplF2Z3FE4PqBAIGyJAQ/w4B5dsqbtQ==}
peerDependencies:
@@ -3337,11 +3349,11 @@ packages:
peerDependencies:
vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
- '@vitest/[email protected]':
- resolution: {integrity: sha512-G9/lgqibheLVBDRuya45EbsEXTYcWoSG+TLg7i2axuzx0Eq62eXn+aWXyaVdV5vKvFSWd6ywcX8hA7la9Pvu8g==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-IM49HmthevbgAO4anp1hwtoT9wYe59w0LR00gr+eagHE+ZJ5lK4sLPeO0ubgoJcwLk6dehU3R24N+FbEEKDc8g==}
peerDependencies:
- '@vitest/browser': 4.1.9
- vitest: 4.1.9
+ '@vitest/browser': 4.1.10
+ vitest: 4.1.10
peerDependenciesMeta:
'@vitest/browser':
optional: true
@@ -3349,11 +3361,11 @@ packages:
'@vitest/[email protected]':
resolution: {integrity: sha512-Io0yyORnB6sikFlt8QW5K7slY4OjqNX9jmJQ02QDda8lyM6B5oNgVWoSoKPac8/kgnCUzuHQKrSLtu/uOqqrig==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-vl/rYsUKcBr3SnQn166+XR5ZQcgMx3DQhFWdfli/cWpLnLUmbxZvyrJZotLFUryib+LtArYMSTJ5RbQ57ZqrlA==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-YsCn+qAk1GWjQOWFEsEcL2gNQ0zmVmQu3T03qP6UyjhtmdtwtbuI+DASn/7iQB3HGTXkdBwGddzxPlmiql5vlA==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-EVkXzBjrPGM+cK8/ANWgBrkUCfJfb38/EfTSO8h7pWvKkyPkpWxvR7BkD2MyItMF62C97zAEoqdpUixwR/e+Rw==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-v0xaezt+DKEmKfaxg133ldzADrwLGd7Ze1MfQQTYfvs8OqZIwbxyxaYURivwV7sWy5fqn3rH5uOrSp07bp44Ow==}
peerDependencies:
msw: ^2.4.9
vite: ^6.0.0 || ^7.0.0 || ^8.0.0
@@ -3366,26 +3378,26 @@ packages:
'@vitest/[email protected]':
resolution: {integrity: sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-s0iufns3iIFitdgm+YR7g1whCAaGtXz459VS9/PqyKDEEFgYIhsHOQmXgIgDuYCt7DeQmiZT0Qe2OA2p4ZPu5A==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-KXLMDtc7oe70+3mJfGrPUWPesswH+3sTxAMAMl8DG7I8IUQT4XW718dY5ID3vPUcmlu27CcKfY4P3h3I29SLJg==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-IKI6kpIH+LmpROplyLwBBaCfMgOZOMsygVa6BARD6ahA04VRuJSa6OaVG7kRvSEMD870Vd91rSSw0eegtWyLGg==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-Jc7RKGNBo8Z28WYIm0Niej4xdSPByRf6mU58VpHQkd6Zh05rlnA+twjbK5HyeIGHxrzsc3mJgS43uM0CZKzaIA==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-xRkfOT1qpTAi/Ti4Y1LtfRc3kEuqxGw59eN2jN9pRWMtS/XDevekhcFSqvQqjUNGksfjMJu3Y+oJ+4Ypn2OaJw==}
'@vitest/[email protected]':
resolution: {integrity: sha512-vAfasCOe6AIK70iP5UD11Ac4siNUNJ9i/9PZ3NKx07sG6sUxeag1LWdNrMWeKKYBLlzuK+Gn65Yd5nyL6ds+nw==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-fHpsS6mIi+PiEW+vcRVOMkX1oSaPKne3VOclSFICPcGOmfKgXPU5iAah+wcNcj2xPrCCmfq99IDGf+EojhhvhA==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw==}
'@vitest/[email protected]':
resolution: {integrity: sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==}
- '@vitest/[email protected]':
- resolution: {integrity: sha512-A51o8ymO5PpqlWNnBP9ZHPXDIpuMtTLlGSjN7la4US+LJzoUMyhwjA5QXlm39JexgwHKW4Xjs8Z2d3dLCXOeuA==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==}
'@webcontainer/[email protected]':
resolution: {integrity: sha512-6aN99yL695Hi9SuIk1oC88l9o0gmxL1nGWWQ/kNy81HigJ0FoaoTXpytCj6ItzgyCEwA9kF1wixsTuv5cjsgng==}
@@ -3949,43 +3961,43 @@ packages:
peerDependencies:
eslint: '>=7'
- resolution: {integrity: sha512-+r4knNhpjjvPEitRWF6j3aiQjxHYcr93QnPFChgt7pChIuifEgIgYeeCj9qwgWk3rGt9YrsESe7s1d9q8iae3w==}
+ resolution: {integrity: sha512-vciXk8shkIcSMMOAKapBr2EDeIHzdcLVZ7VZKOqePh+Gspg8cIcu3QB+3P4sOu67G50r7csCU0Gv4D2S/aeKSw==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- resolution: {integrity: sha512-XVQs2v9pekKzvO2FUtqVLPdmq+UNLal1YPS3rWwcCYney41GzT2SA7lzQ/t9sRkoclQf/DTE7jqQiUHN7RBoDA==}
+ resolution: {integrity: sha512-TM3vEHNqYjg0oOhkK3wb2W1xw58a+WDtbScXEjPY4IsmfjlDh/v8DuSHu+gf1Irtv0JhtM39GHKrJ8TlcuZ0NA==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- resolution: {integrity: sha512-prEXjlQM7s6xql23g4AETipAyhY3Fu9h4SbGS3LtRBhwBu+oB0MR1ksiZ2LK7jQr3jMb7ZgL7L5oYzbU/i5ZzQ==}
+ resolution: {integrity: sha512-ew034YtKNX6gUXBJhqvaxwNKmMVTReSkdpFpzNbwf7nbliG3X5s6EWgDYa5bBeu1/yzYv4bNMINdJCqdJnd9ig==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- resolution: {integrity: sha512-I6sJJW9ZrSrHPhOcV7oB4L8VLon60Q0DNMKOnsKthp0pk0Y0OTQ7CkPnHVzvGlOW80KdBZJFYLy8pRA4IHYV9w==}
+ resolution: {integrity: sha512-gvD/G8n8JxUOO+O+g94AcbI3qifiqfVMfsHrfuOmrDa5TDuWbXRpSEy31bz76AT/aSh7qmVaE1bV4Ynl9NCh1g==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- resolution: {integrity: sha512-dI+7rmSuxKYtq9XjJVkowSgCiyIAc8IU6Xzt6uJagAl6vrnMxiDwnzKLwAKUheRQdNTMDOVqPY04gJ4m4YxsbA==}
+ resolution: {integrity: sha512-3nthRL7fkc6aKXkJSIQL3Q3lpDrofGu8Xlz6CYLkTCcglqrmma8IkqwpHSNuuE65mFDQfI4u5G2mEI+SUtEq0Q==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
typescript: '*'
- resolution: {integrity: sha512-Lslxif5p0rKviGUdxPc7KIsNkEwkaZGoqFcTi4/ji6Ht1NylJkcV80p4dU6ZLgdaIAaQD2QG/m3i4QuoxLXfFA==}
+ resolution: {integrity: sha512-vopujDcrwH34+Y44xy3TFieR2WgCrxFXiPLWoz8jMBc4MMpKEoR8HxJsdymlG5lbbOnHWHWkXRVVUCLyF5+79A==}
engines: {node: '>=22.0.0'}
peerDependencies:
eslint: '*'
@@ -4346,6 +4358,9 @@ packages:
resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-cGzymZerpDhVXRKjKLgXKda9gI29TU2o88L7gwNMHp3WZVxA/0c5tX52udXbW9JklDApolvMXZG6Dhhdz5eirA==}
+
resolution: {integrity: sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==}
@@ -5811,20 +5826,20 @@ packages:
yaml:
optional: true
- resolution: {integrity: sha512-nE3/LEyc0z87uHYLZebqCUOaJr2hdtuPp7BQ4BosVFnfltxgAvMG08NyrSGlPpOUWvR27c5flSmYFTNr78L9GQ==}
+ resolution: {integrity: sha512-R9jUTe5S4Qb0HCd4TNqpC7oGcrMssMRGXLW80ubjWsW9VH5GF8y1Y0SFLY9AbqSk6nt0PnOx4H4WNJYZ13GUPw==}
engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
hasBin: true
peerDependencies:
'@edge-runtime/vm': '*'
'@opentelemetry/api': ^1.9.0
'@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
- '@vitest/browser-playwright': 4.1.9
- '@vitest/browser-preview': 4.1.9
- '@vitest/browser-webdriverio': 4.1.9
- '@vitest/coverage-istanbul': 4.1.9
- '@vitest/coverage-v8': 4.1.9
- '@vitest/ui': 4.1.9
+ '@vitest/browser-playwright': 4.1.10
+ '@vitest/browser-preview': 4.1.10
+ '@vitest/browser-webdriverio': 4.1.10
+ '@vitest/coverage-istanbul': 4.1.10
+ '@vitest/coverage-v8': 4.1.10
+ '@vitest/ui': 4.1.10
happy-dom: '*'
jsdom: '*'
vite: ^6.0.0 || ^7.0.0 || ^8.0.0
@@ -6678,7 +6693,7 @@ snapshots:
'@eslint-community/[email protected]': {}
dependencies:
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/typescript-estree': 8.62.1([email protected])
@@ -6689,13 +6704,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/scope-manager': 8.62.1
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
@@ -6705,21 +6720,21 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
- eslint-plugin-react-dom: 5.10.4([email protected]([email protected]))([email protected])
- eslint-plugin-react-jsx: 5.10.4([email protected]([email protected]))([email protected])
- eslint-plugin-react-naming-convention: 5.10.4([email protected]([email protected]))([email protected])
- eslint-plugin-react-rsc: 5.10.4([email protected]([email protected]))([email protected])
- eslint-plugin-react-web-api: 5.10.4([email protected]([email protected]))([email protected])
- eslint-plugin-react-x: 5.10.4([email protected]([email protected]))([email protected])
+ eslint-plugin-react-dom: 5.11.2([email protected]([email protected]))([email protected])
+ eslint-plugin-react-jsx: 5.11.2([email protected]([email protected]))([email protected])
+ eslint-plugin-react-naming-convention: 5.11.2([email protected]([email protected]))([email protected])
+ eslint-plugin-react-rsc: 5.11.2([email protected]([email protected]))([email protected])
+ eslint-plugin-react-web-api: 5.11.2([email protected]([email protected]))([email protected])
+ eslint-plugin-react-x: 5.11.2([email protected]([email protected]))([email protected])
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
@@ -6727,12 +6742,12 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
@@ -6741,9 +6756,9 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
ts-pattern: 5.9.0
@@ -6752,10 +6767,10 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/scope-manager': 8.62.1
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
@@ -6811,6 +6826,14 @@ snapshots:
'@floating-ui/[email protected]': {}
+ '@formatjs/[email protected]': {}
+
+ '@formatjs/[email protected]':
+ dependencies:
+ '@formatjs/icu-skeleton-parser': 2.1.10
+
+ '@formatjs/[email protected]': {}
+
dependencies:
react: 19.2.7
@@ -8369,10 +8392,10 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
'@bcoe/v8-coverage': 1.0.2
- '@vitest/utils': 4.1.9
+ '@vitest/utils': 4.1.10
ast-v8-to-istanbul: 1.0.4
istanbul-lib-coverage: 3.2.2
istanbul-lib-report: 3.0.1
@@ -8381,7 +8404,7 @@ snapshots:
obug: 2.1.3
std-env: 4.1.0
tinyrainbow: 3.1.0
'@vitest/[email protected]':
dependencies:
@@ -8391,18 +8414,18 @@ snapshots:
chai: 5.3.3
tinyrainbow: 2.0.0
- '@vitest/[email protected]':
+ '@vitest/[email protected]':
dependencies:
'@standard-schema/spec': 1.1.0
'@types/chai': 5.2.3
- '@vitest/spy': 4.1.9
- '@vitest/utils': 4.1.9
+ '@vitest/spy': 4.1.10
+ '@vitest/utils': 4.1.10
chai: 6.2.2
tinyrainbow: 3.1.0
dependencies:
- '@vitest/spy': 4.1.9
+ '@vitest/spy': 4.1.10
estree-walker: 3.0.3
magic-string: 0.30.21
optionalDependencies:
@@ -8412,19 +8435,19 @@ snapshots:
dependencies:
tinyrainbow: 2.0.0
- '@vitest/[email protected]':
+ '@vitest/[email protected]':
dependencies:
tinyrainbow: 3.1.0
- '@vitest/[email protected]':
+ '@vitest/[email protected]':
dependencies:
- '@vitest/utils': 4.1.9
+ '@vitest/utils': 4.1.10
pathe: 2.0.3
- '@vitest/[email protected]':
+ '@vitest/[email protected]':
dependencies:
- '@vitest/pretty-format': 4.1.9
- '@vitest/utils': 4.1.9
+ '@vitest/pretty-format': 4.1.10
+ '@vitest/utils': 4.1.10
magic-string: 0.30.21
pathe: 2.0.3
@@ -8432,7 +8455,7 @@ snapshots:
dependencies:
tinyspy: 4.0.4
- '@vitest/[email protected]': {}
+ '@vitest/[email protected]': {}
'@vitest/[email protected]':
dependencies:
@@ -8440,9 +8463,9 @@ snapshots:
loupe: 3.2.1
tinyrainbow: 2.0.0
- '@vitest/[email protected]':
+ '@vitest/[email protected]':
dependencies:
- '@vitest/pretty-format': 4.1.9
+ '@vitest/pretty-format': 4.1.10
convert-source-map: 2.0.0
tinyrainbow: 3.1.0
@@ -8973,12 +8996,12 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
compare-versions: 6.1.1
@@ -8987,13 +9010,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/core': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/core': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
@@ -9001,12 +9024,12 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/core': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/core': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
@@ -9015,13 +9038,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/core': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/core': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
eslint: 10.6.0([email protected])
@@ -9029,13 +9052,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/core': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/core': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
'@typescript-eslint/utils': 8.62.1([email protected]([email protected]))([email protected])
birecord: 0.1.1
@@ -9045,14 +9068,14 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-react/core': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/eslint': 5.10.4([email protected]([email protected]))([email protected])
- '@eslint-react/shared': 5.10.4([email protected]([email protected]))([email protected])
+ '@eslint-react/core': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/eslint': 5.11.2([email protected]([email protected]))([email protected])
+ '@eslint-react/shared': 5.11.2([email protected]([email protected]))([email protected])
'@typescript-eslint/scope-manager': 8.62.1
'@typescript-eslint/type-utils': 8.62.1([email protected]([email protected]))([email protected])
'@typescript-eslint/types': 8.62.1
@@ -9460,6 +9483,11 @@ snapshots:
+ dependencies:
+ '@formatjs/fast-memoize': 3.1.6
+ '@formatjs/icu-messageformat-parser': 3.5.12
+
dependencies:
loose-envify: 1.4.0
@@ -11061,15 +11089,15 @@ snapshots:
tsx: 4.23.0
yaml: 2.9.0
dependencies:
- '@vitest/expect': 4.1.9
- '@vitest/pretty-format': 4.1.9
- '@vitest/runner': 4.1.9
- '@vitest/snapshot': 4.1.9
- '@vitest/spy': 4.1.9
- '@vitest/utils': 4.1.9
+ '@vitest/expect': 4.1.10
+ '@vitest/pretty-format': 4.1.10
+ '@vitest/runner': 4.1.10
+ '@vitest/snapshot': 4.1.10
+ '@vitest/spy': 4.1.10
+ '@vitest/utils': 4.1.10
es-module-lexer: 2.3.0
expect-type: 1.4.0
magic-string: 0.30.21
@@ -11085,7 +11113,7 @@ snapshots:
why-is-node-running: 2.3.0
optionalDependencies:
'@types/node': 25.9.4
- '@vitest/coverage-v8': 4.1.9([email protected])
+ '@vitest/coverage-v8': 4.1.10([email protected])
jsdom: 27.4.0
transitivePeerDependencies:
- msw
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index 60d38f510e..808ddd2aae 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -85,6 +85,12 @@ const STATIC_EXPORTS = {
},
'./docs.mjs': './docs.mjs',
'./groups.doc.mjs': './groups.doc.mjs',
+ // i18n message catalogs. Consumers pass these to
+ // <InternationalizationProvider messages={{fr, ...}}> or use them for
+ // custom overrides / pseudoloc smoke-tests. Wildcard export exposes every
+ // JSON file under packages/core/locales/, which ships thanks to the
+ // `locales` entry in the `files` array.
+ './locales/*.json': './locales/*.json',
};
/**
diff --git a/vitest.config.ts b/vitest.config.ts
index c8d5b292a5..31acd414b3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -75,6 +75,7 @@ export default defineConfig({
exclude: ['**/*.test.{ts,tsx}', '**/*.stories.{ts,tsx}', '**/index.ts'],
},
setupFiles: ['./internal/test-utils/src/setup.ts'],
+ globalSetup: ['./internal/test-utils/src/globalSetup.ts'],
// Increase worker heap to prevent OOM crashes on memory-heavy test files
// (e.g. Chat composer tests with contentEditable + popover portals in
// jsdom). Vitest 4 removed `poolOptions`; per-worker argv is now top-level.