An open source design system that's fully customizable and agent ready
TypeScript
Generate compact runtime locale catalogs (#6697)
nynexman446414d078e19d5e
diff --git a/.changeset/lean-runtime-i18n.md b/.changeset/lean-runtime-i18n.mdnew file mode 100644index 0000000000..18fd833f2c--- /dev/null+++ b/.changeset/lean-runtime-i18n.md@@ -0,0 +1,9 @@+---+'@astryxdesign/core': patch+---++[feat] Stop bundling translator-only descriptions with the built-in English+fallback and add compact generated string-map modules for every shipped locale.+Existing rich JSON catalog exports remain unchanged.++@nynexman4464diff --git a/.gitignore b/.gitignoreindex a5e606d507..018869fd43 100644--- a/.gitignore+++ b/.gitignore@@ -83,8 +83,9 @@ mise.toml# Generated shadcn Registry output (rebuilt by the docsite generate step)apps/docsite/public/shadcn/-# Generated i18n artifacts (rebuilt from en.json)+# Generated i18n artifacts (rebuilt from en.json and translated catalogs)packages/core/locales/pseudo.json+packages/core/src/i18n/generated-locales/# Generated lab readiness report (rebuild with `pnpm lab:readiness`).# Deliberately not committed: a checked-in snapshot goes stale the moment thediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 366ac19571..427ff6a736 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -115,8 +115,9 @@ Storybook will open at http://localhost:6006 with:- **Mode switcher** - Toggle between Light and Dark modes- **Component stories** - Interactive component examples-**If you make changes to `@astryxdesign/core`:** nothing extra. The dev server-serves the edited source, so the story updates on save — no rebuild, no restart.+**If you make changes to `@astryxdesign/core`:** ordinary source changes update+without a rebuild or restart. After editing `packages/core/locales/*.json`,+restart Storybook; rebuild Core before restarting the docsite.### Running the Doc Sitediff --git a/apps/storybook/package.json b/apps/storybook/package.jsonindex fbabf5dfea..2900f4dc1c 100644--- a/apps/storybook/package.json+++ b/apps/storybook/package.json@@ -3,8 +3,8 @@"version": "0.0.1","private": true,"scripts": {- "dev": "storybook dev -p 6006",- "build": "storybook build -o dist",+ "dev": "node ../../scripts/generate-i18n-runtime.mjs && storybook dev -p 6006",+ "build": "node ../../scripts/generate-i18n-runtime.mjs && storybook build -o dist","rtl-audit": "node rtl-audit/rtl-audit.mjs --storybook-dir dist --output rtl-audit-report.json","typecheck": "tsc --noEmit"},diff --git a/internal/test-utils/src/globalSetup.ts b/internal/test-utils/src/globalSetup.tsindex 5ee55bcd1d..32a13d9fb3 100644--- a/internal/test-utils/src/globalSetup.ts+++ b/internal/test-utils/src/globalSetup.ts@@ -3,13 +3,13 @@/*** @file globalSetup.ts* @input None (runs once, before the whole test suite)- * @output Side effect: regenerates packages/core/locales/pseudo.json+ * @output Side effect: regenerates the English runtime catalog and 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.+ * Both files are git-ignored and derived from en.json. This setup runs their+ * generators once per test suite so source-mode tests always use current+ * English and pseudo messages.*/import {execFileSync} from 'node:child_process';@@ -21,12 +21,11 @@ const HERE = dirname(fileURLToPath(import.meta.url));export default function setup() {// internal/test-utils/src → repo rootconst repoRoot = resolve(HERE, '..', '..', '..');- const script = resolve(- repoRoot,- 'packages',- 'core',- 'scripts',- 'build-pseudo-locale.mjs',- );- execFileSync('node', [script], {stdio: 'inherit'});+ const scripts = [+ resolve(repoRoot, 'scripts', 'generate-i18n-runtime.mjs'),+ resolve(repoRoot, 'packages', 'core', 'scripts', 'build-pseudo-locale.mjs'),+ ];+ for (const script of scripts) {+ execFileSync(process.execPath, [script], {stdio: 'inherit'});+ }}diff --git a/package.json b/package.jsonindex f754d75d0f..114d97c8b7 100644--- a/package.json+++ b/package.json@@ -13,7 +13,7 @@"test:a11y-contract": "playwright test --config playwright.config.ts --project chromium","test:docsite-browser": "playwright test --config apps/docsite/playwright.config.ts","check:package-boundaries": "node scripts/check-package-boundaries.js",- "check:repo": "pnpm check:visual-owner && pnpm check:sync && pnpm check:knowledge && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure && pnpm check:use-client && pnpm check:portable-scripts && pnpm check:i18n-catalog && pnpm check:cldr-weekdays && pnpm check:fixtures && pnpm check:setup-contract",+ "check:repo": "pnpm check:visual-owner && pnpm check:sync && pnpm check:knowledge && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure && pnpm check:use-client && pnpm check:portable-scripts && pnpm check:i18n-runtime && pnpm check:i18n-catalog && pnpm check:cldr-weekdays && pnpm check:fixtures && pnpm check:setup-contract","check:visual-owner": "node scripts/check-visual-workflow-owner.mjs","check:fixtures": "node internal/vibe-tests/scripts/fixture-suite.mjs verify","generate:cldr-weekdays": "node scripts/generate-cldr-weekdays.mjs",@@ -25,6 +25,8 @@"generate:setup-contract": "node scripts/generate-setup-contract.mjs","check:executable-bits": "node scripts/check-executable-bits.mjs","check:demo-media": "node scripts/check-demo-media.mjs",+ "generate:i18n-runtime": "node scripts/generate-i18n-runtime.mjs",+ "check:i18n-runtime": "node scripts/generate-i18n-runtime.mjs --check","check:i18n-catalog": "node scripts/check-i18n-catalog.mjs","check:sync": "node scripts/check-sync.js","check:use-client": "node scripts/check-use-client.mjs",@@ -61,9 +63,9 @@"setup-trusted-publishing": "node scripts/npm/setup-trusted-publishing.mjs","verify-exports": "node scripts/verify-exports.mjs","release": "pnpm build && changeset publish",- "prepare": "husky install",+ "prepare": "node scripts/generate-i18n-runtime.mjs --best-effort && husky install","dev:sandbox": "pnpm -F @astryxdesign/core build && pnpm -F @astryxdesign/sandbox dev",- "dev:sandbox:source": "ASTRYX_SOURCE=1 pnpm -F @astryxdesign/sandbox dev",+ "dev:sandbox:source": "pnpm generate:i18n-runtime && ASTRYX_SOURCE=1 pnpm -F @astryxdesign/sandbox dev","npm:prune-canaries": "node scripts/npm/prune-canaries.mjs","check:knowledge": "node scripts/check-knowledge.mjs"},diff --git a/packages/build/src/vite.build.test.ts b/packages/build/src/vite.build.test.tsindex 1ca1878e64..fa55a8bc3b 100644--- a/packages/build/src/vite.build.test.ts+++ b/packages/build/src/vite.build.test.ts@@ -33,7 +33,16 @@import {describe, it, expect, beforeAll, afterAll} from 'vitest';import {build} from 'vite';import react from '@vitejs/plugin-react';-import {mkdtempSync, readdirSync, readFileSync, rmSync} from 'node:fs';+import {+ mkdirSync,+ mkdtempSync,+ readdirSync,+ readFileSync,+ realpathSync,+ rmSync,+ symlinkSync,+ writeFileSync,+} from 'node:fs';import {tmpdir} from 'node:os';import * as path from 'node:path';import {fileURLToPath} from 'node:url';@@ -43,6 +52,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));const REPO_ROOT = path.resolve(__dirname, '../../..');const FIXTURES = path.resolve(__dirname, '../__fixtures__');const CORE_SRC = path.join(REPO_ROOT, 'packages/core/src');+const CORE_PACKAGE = path.join(REPO_ROOT, 'packages/core');/** The class prefixes @astryxdesign/build/babel assigns per origin. */const LIBRARY_CLASS = /\.astryx[a-z0-9]{5,}/g;@@ -205,6 +215,43 @@ function itSplitsCorrectly(get: () => Built) {});}+describe('a production build resolves generated locale modules', () => {+ it('loads a generated string map through the standard Astryx Vite aliases', async () => {+ const root = realpathSync(+ mkdtempSync(path.join(tmpdir(), 'astryx-locale-import-')),+ );+ const packageDir = path.join(root, 'node_modules/@astryxdesign');+ const outDir = path.join(root, 'dist');+ mkdirSync(packageDir, {recursive: true});+ symlinkSync(CORE_PACKAGE, path.join(packageDir, 'core'), 'dir');+ writeFileSync(+ path.join(root, 'index.html'),+ '<script type="module" src="/main.ts"></script>',+ );+ writeFileSync(+ path.join(root, 'main.ts'),+ `import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';\ndocument.body.textContent = frFR['@astryx.pagination.next'];\n`,+ );++ try {+ await build({+ root,+ logLevel: 'error',+ build: {outDir, emptyOutDir: true, minify: false},+ plugins: [...astryxStylex({rootDir: root})],+ });+ const assets = path.join(outDir, 'assets');+ const jsName = readdirSync(assets).find(file => file.endsWith('.js'));+ expect(jsName).toBeTruthy();+ expect(readFileSync(path.join(assets, jsName!), 'utf8')).toContain(+ 'Aller à la page suivante',+ );+ } finally {+ rmSync(root, {recursive: true, force: true});+ }+ }, 180_000);+});+describe('a production build separates Astryx and product styles by layer', () => {describe('when the app imports a stylesheet of its own', () => {let built: Built;diff --git a/packages/build/src/vite.test.ts b/packages/build/src/vite.test.tsindex e0043aac67..5d888896f4 100644--- a/packages/build/src/vite.test.ts+++ b/packages/build/src/vite.test.ts@@ -16,6 +16,26 @@ import {astryxStylex} from './vite';const __dirname = path.dirname(fileURLToPath(import.meta.url));+function getInjectedConfig(rootDir: string): any {+ const plugins = astryxStylex({rootDir});+ const configPlugin = plugins.find(p => p.name === 'astryx-config');+ expect(configPlugin, 'astryx-config plugin should exist').toBeTruthy();+ const config = (configPlugin as any).config;+ return typeof config === 'function' ? config() : config.handler();+}++function applyAlias(aliases: any[], id: string): string {+ for (const alias of aliases) {+ if (+ (typeof alias.find === 'string' && id.startsWith(alias.find)) ||+ (alias.find instanceof RegExp && alias.find.test(id))+ ) {+ return id.replace(alias.find, alias.replacement);+ }+ }+ return id;+}+/** Pull the injected `@layer ...;` order statement out of the plugin set. */function getLayerOrder(plugins: ReturnType<typeof astryxStylex>): string {const layerPlugin = plugins.find(p => p.name === 'astryx-css-layer-order');@@ -99,6 +119,26 @@ describe('astryxStylex build-time layer split', () => {});});+describe('astryxStylex locale aliases', () => {+ it('routes generated and rich locale imports to their real package files', () => {+ const rootDir = path.join(tmpdir(), 'astryx-vite-alias');+ const aliases = getInjectedConfig(rootDir).resolve.alias;+ const corePackage = path.join(rootDir, 'node_modules/@astryxdesign/core');++ expect(+ applyAlias(aliases, '@astryxdesign/core/locales/fr-FR.generated.js'),+ ).toBe(+ path.join(corePackage, 'src/i18n/generated-locales/fr-FR.generated.ts'),+ );+ expect(applyAlias(aliases, '@astryxdesign/core/locales/fr-FR.json')).toBe(+ path.join(corePackage, 'locales/fr-FR.json'),+ );+ expect(applyAlias(aliases, '@astryxdesign/core/Button')).toBe(+ path.join(corePackage, 'src/Button'),+ );+ });+});+describe('astryxStylex optimizeDeps package discovery', () => {let rootDir: string;diff --git a/packages/build/src/vite.ts b/packages/build/src/vite.tsindex f1b819d319..54a2359618 100644--- a/packages/build/src/vite.ts+++ b/packages/build/src/vite.ts@@ -204,18 +204,35 @@ export function astryxStylex(// Fallback to just @astryxdesign/core if discovery fails}+ const corePackageDir = path.resolve(+ rootDir,+ 'node_modules/@astryxdesign/core',+ );+ const coreSourceDir = path.join(corePackageDir, 'src');+return {resolve: {- alias: {- '@astryxdesign/core/theme/tokens.stylex': path.resolve(- rootDir,- 'node_modules/@astryxdesign/core/src/theme/tokens.stylex.ts',- ),- '@astryxdesign/core': path.resolve(- rootDir,- 'node_modules/@astryxdesign/core/src',- ),- },+ alias: [+ {+ find: /^@astryxdesign\/core\/locales\/(.+)\.generated\.js$/,+ replacement: path.join(+ coreSourceDir,+ 'i18n/generated-locales/$1.generated.ts',+ ),+ },+ {+ find: /^@astryxdesign\/core\/locales\/(.+)\.json$/,+ replacement: path.join(corePackageDir, 'locales/$1.json'),+ },+ {+ find: '@astryxdesign/core/theme/tokens.stylex',+ replacement: path.join(coreSourceDir, 'theme/tokens.stylex.ts'),+ },+ {+ find: '@astryxdesign/core',+ replacement: coreSourceDir,+ },+ ],},optimizeDeps: {exclude: xdsPackages,diff --git a/packages/cli/assets/docs/internationalization.doc.mjs b/packages/cli/assets/docs/internationalization.doc.mjsindex 45d8504666..2f6091dd84 100644--- a/packages/cli/assets/docs/internationalization.doc.mjs+++ b/packages/cli/assets/docs/internationalization.doc.mjs@@ -41,15 +41,17 @@ function App() {lang: 'tsx',label: 'Load an astryx locale catalog',code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';-import fr from '@astryxdesign/core/locales/fr.json';+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';-<InternationalizationProvider locale="fr" messages={{fr}}>+<InternationalizationProvider+ locale="fr-FR"+ messages={{'fr-FR': frFR}}><App /></InternationalizationProvider>;`,},{type: 'prose',- text: 'Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',+ text: 'Astryx ships English and first-party translations for supported locales. Compact runtime modules from `@astryxdesign/core/locales/*.generated.js` contain only the messages apps need; the existing `@astryxdesign/core/locales/*.json` files retain translator context. Until a locale is available, apps can pass a local catalog in either shape. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',},{type: 'prose',@@ -290,7 +292,7 @@ export default function App() {},{type: 'prose',- text: '`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.',+ text: '`Catalog` types the rich `{defaultMessage, description?}` authoring shape. `RuntimeCatalog` types the generated key-to-message string map. `ProviderMessagesByLocale` accepts either shape for the provider, while `MessagesByLocale` keeps the original rich-only context shape.',},],},@@ -307,7 +309,7 @@ export default function App() {lang: 'tsx',label: 'Turn on pseudo-localization',code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';-import pseudo from '@astryxdesign/core/locales/pseudo.json';+import pseudo from '@astryxdesign/core/locales/pseudo.generated.js';<InternationalizationProvider locale="pseudo" messages={{pseudo}}><App />diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsxindex 1ceb58193b..2ec6056dc0 100644--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx@@ -4,7 +4,7 @@import {useState} from 'react';import {InternationalizationProvider} from '@astryxdesign/core/i18n';-import frFR from '@astryxdesign/core/locales/fr-FR.json';+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';import {Stack} from '@astryxdesign/core/Layout';import {SegmentedControl,diff --git a/packages/core/package.json b/packages/core/package.jsonindex 517a45af7e..62a6c4ead2 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -79,6 +79,11 @@"./docs.mjs": "./docs.mjs","./groups.doc.mjs": "./groups.doc.mjs","./locales/*.json": "./locales/*.json",+ "./locales/*.generated.js": {+ "source": "./src/i18n/generated-locales/*.generated.ts",+ "types": "./dist/i18n/generated-locales/*.generated.d.ts",+ "default": "./dist/i18n/generated-locales/*.generated.js"+ },"./AlertDialog": {"source": "./src/AlertDialog/index.ts","types": "./dist/AlertDialog/index.d.ts",@@ -690,7 +695,7 @@"prepack": "pnpm build","postinstall": "node scripts/postinstall.mjs","build": "node ../../scripts/clean-dist.mjs && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",- "build:i18n": "node scripts/build-pseudo-locale.mjs",+ "build:i18n": "node ../../scripts/generate-i18n-runtime.mjs && 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","dev": "babel src --watch --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css*\" --config-file ./babel.config.json",diff --git a/packages/core/scripts/build-pseudo-locale.mjs b/packages/core/scripts/build-pseudo-locale.mjsindex 32c5ee3f32..07805828a5 100644--- a/packages/core/scripts/build-pseudo-locale.mjs+++ b/packages/core/scripts/build-pseudo-locale.mjs@@ -17,7 +17,7 @@* Runs as part of the core build so pseudo.json stays in sync with en.json.*/-import {readFileSync, writeFileSync} from 'node:fs';+import {readFileSync, realpathSync, writeFileSync} from 'node:fs';import {resolve, dirname} from 'node:path';import {fileURLToPath} from 'node:url';@@ -36,7 +36,7 @@ const ACCENTED = {Y: 'Ý', Z: 'Ž',};-function pseudoTranslate(msg) {+export function pseudoTranslate(msg) {let out = '';let depth = 0;for (const ch of msg) {@@ -48,11 +48,24 @@ function pseudoTranslate(msg) {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)};+export function createPseudoCatalog(en) {+ const pseudo = {};+ for (const [key, entry] of Object.entries(en)) {+ pseudo[key] = {defaultMessage: pseudoTranslate(entry.defaultMessage)};+ }+ return pseudo;+}++function main() {+ const en = JSON.parse(readFileSync(EN_PATH, 'utf8'));+ const pseudo = createPseudoCatalog(en);+ writeFileSync(PSEUDO_PATH, JSON.stringify(pseudo, null, 2) + '\n', 'utf8');+ console.log(`Built pseudo.json — ${Object.keys(pseudo).length} keys`);}-writeFileSync(PSEUDO_PATH, JSON.stringify(pseudo, null, 2) + '\n', 'utf8');-console.log(`Built pseudo.json — ${Object.keys(pseudo).length} keys`);+if (+ process.argv[1] &&+ realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))+) {+ main();+}diff --git a/packages/core/src/i18n/InternationalizationProvider.doc.mjs b/packages/core/src/i18n/InternationalizationProvider.doc.mjsindex 83741aa06a..2e4a3ab11d 100644--- a/packages/core/src/i18n/InternationalizationProvider.doc.mjs+++ b/packages/core/src/i18n/InternationalizationProvider.doc.mjs@@ -35,17 +35,17 @@ export const docs = {{guidance: true,description:- 'Use real BCP 47 tags such as `fr`, `pt-BR`, or `ar`; regional locales fall back to their base language before English.',+ 'Use real BCP 47 tags such as `fr-FR`, `pt-BR`, or `ar-SA`; regional locales fall back to their base language before English.',},{guidance: true,description:- 'Set the `dir` attribute on `<html>` (or a wrapping element) yourself; the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won\'t visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.',+ "Set the `dir` attribute on `<html>` (or a wrapping element) yourself; the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won't visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.",},{guidance: false,description:- 'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',+ 'Cast custom catalog maps to `any`; the i18n package exports `ProviderMessagesByLocale`, `MessagesByLocale`, `Catalog`, and `RuntimeCatalog` for local catalog typing.',},],},@@ -59,10 +59,10 @@ export const docs = {},{name: 'messages',- type: 'MessagesByLocale',+ type: 'ProviderMessagesByLocale',required: false,description:- 'Optional map of BCP 47 tag to translation catalog. Import shipped catalogs from `@astryxdesign/core/locales/*`; the shipped "en" catalog is always available and does not need to be listed here.',+ 'Optional map of BCP 47 tag to a rich or generated runtime catalog. Import compact shipped catalogs from `@astryxdesign/core/locales/*.generated.js`; the shipped "en" catalog is always available and does not need to be listed here.',},{name: 'overrides',@@ -90,7 +90,7 @@ export const docs = {label: 'Load a shipped Astryx locale catalog',code: `import type {ReactNode} from 'react';import {InternationalizationProvider} from '@astryxdesign/core/i18n';-import frFR from '@astryxdesign/core/locales/fr-FR.json';+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';export function AppI18n({children}: {children: ReactNode}) {return (@@ -151,17 +151,17 @@ export const docsDense = {{guidance: true,description:- 'Use shipped Astryx locale catalogs from `@astryxdesign/core/locales/*` when one exists for the target locale.',+ 'Use compact shipped Astryx catalogs from `@astryxdesign/core/locales/*.generated.js` when one exists for the target locale.',},{guidance: true,description:- 'Use a same-shape local catalog only when Astryx has not shipped that locale yet or when testing in-progress translations.',+ 'Use a rich `Catalog` or compact `RuntimeCatalog` when Astryx has not shipped the target locale or when testing in-progress translations.',},{guidance: true,description:- 'Use real BCP 47 tags like `fr`, `pt-BR`, or `ar`; regional locales fall back to base language before English.',+ 'Use real BCP 47 tags like `fr-FR`, `pt-BR`, or `ar-SA`; regional locales fall back to base language before English.',},{guidance: true,@@ -171,7 +171,7 @@ export const docsDense = {{guidance: false,description:- 'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',+ 'Cast custom catalog maps to `any`; the i18n package exports `ProviderMessagesByLocale`, `MessagesByLocale`, `Catalog`, and `RuntimeCatalog` for local catalog typing.',},],},@@ -179,7 +179,7 @@ export const docsDense = {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',+ 'map of BCP 47 tag to a rich Catalog or generated RuntimeCatalog; "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.tsxindex 81f0d5b9ab..84f2f91fc9 100644--- a/packages/core/src/i18n/InternationalizationProvider.tsx+++ b/packages/core/src/i18n/InternationalizationProvider.tsx@@ -22,9 +22,37 @@import {useMemo, type ReactNode} from 'react';import {InternationalizationContext} from './InternationalizationContext';import {getLocaleDirection} from './getLocaleDirection';-import type {Locale, MessagesByLocale, Overrides} from './types';+import type {+ Locale,+ MessagesByLocale,+ Overrides,+ ProviderMessagesByLocale,+} from './types';import {getResolve} from './resolve';+function normalizeMessages(+ messages: ProviderMessagesByLocale,+): MessagesByLocale {+ const hasRuntimeCatalog = Object.values(messages).some(catalog =>+ Object.values(catalog).some(entry => typeof entry === 'string'),+ );+ if (!hasRuntimeCatalog) {+ return messages as MessagesByLocale;+ }++ return Object.fromEntries(+ Object.entries(messages).map(([locale, catalog]) => [+ locale,+ Object.fromEntries(+ Object.entries(catalog).map(([key, entry]) => [+ key,+ typeof entry === 'string' ? {defaultMessage: entry} : entry,+ ]),+ ),+ ]),+ );+}+export interface InternationalizationProviderProps {/*** BCP 47 language tag. Examples: `'en'`, `'pt'`, `'pt-BR'`, `'zh-Hans'`.@@ -40,11 +68,13 @@ export interface InternationalizationProviderProps {** @example* ```- * import {fr} from '@astryxdesign/core/locales/fr.json';- * <InternationalizationProvider locale="fr" messages={{fr}}>+ * import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';+ * <InternationalizationProvider+ * locale="fr-FR"+ * messages={{'fr-FR': frFR}}>* ```*/- messages?: MessagesByLocale;+ messages?: ProviderMessagesByLocale;/*** Sparse per-locale overrides applied on top of shipped defaults.* Only the keys you want to override need to be listed.@@ -85,16 +115,16 @@ export function InternationalizationProvider({children,}: InternationalizationProviderProps) {const direction = dir ?? getLocaleDirection(locale);- const value = useMemo(- () => ({+ const value = useMemo(() => {+ const providedMessages = messages ?? {};+ return {locale,direction,- messages: messages ?? {},+ messages: normalizeMessages(providedMessages),overrides,- translate: getResolve(locale, messages ?? {}, overrides),- }),- [locale, direction, messages, overrides],- );+ translate: getResolve(locale, providedMessages, overrides),+ };+ }, [locale, direction, messages, overrides]);return (<InternationalizationContext value={value}>{children}diff --git a/packages/core/src/i18n/__tests__/resolve.test.ts b/packages/core/src/i18n/__tests__/resolve.test.tsindex 4f6c5fb3a2..88b0e7efb9 100644--- a/packages/core/src/i18n/__tests__/resolve.test.ts+++ b/packages/core/src/i18n/__tests__/resolve.test.ts@@ -10,7 +10,12 @@import {describe, expect, test, beforeEach, vi} from 'vitest';import {__resetForTests, getResolve, resolveLocaleChain} from '../resolve';-import type {Catalog, MessagesByLocale, Overrides} from '../types';+import type {+ Catalog,+ MessagesByLocale,+ Overrides,+ ProviderMessagesByLocale,+} from '../types';const resolve = (...[key, values, locale, messages, overrides]: [@@ -57,8 +62,8 @@ describe('resolveLocaleChain', () => {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.+ // The compact shipped English catalog is loaded at module initialization;+ // Pagination keys should resolve. This asserts the module wiring end-to-end.const out = resolve('@astryx.pagination.next',undefined,@@ -101,6 +106,20 @@ describe('resolve — provider messages', () => {expect(out).toBe('Suivant');});+ test('uses a generated runtime string map for the current locale', () => {+ const runtimeMessages: ProviderMessagesByLocale = {+ fr: {'@astryx.pagination.next': 'Suivant compact'},+ };+ const out = resolve(+ '@astryx.pagination.next',+ undefined,+ 'fr',+ runtimeMessages,+ undefined,+ );+ expect(out).toBe('Suivant compact');+ });+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 — thediff --git a/packages/core/src/i18n/index.ts b/packages/core/src/i18n/index.tsindex 927b7a559c..3bed7c1a8c 100644--- a/packages/core/src/i18n/index.ts+++ b/packages/core/src/i18n/index.ts@@ -39,6 +39,8 @@ export type {Locale,Catalog,MessageEntry,+ RuntimeCatalog,MessagesByLocale,+ ProviderMessagesByLocale,Overrides,} from './types';diff --git a/packages/core/src/i18n/resolve.ts b/packages/core/src/i18n/resolve.tsindex 87c9a505e6..120551ef7d 100644--- a/packages/core/src/i18n/resolve.ts+++ b/packages/core/src/i18n/resolve.ts@@ -20,12 +20,10 @@*/import IntlMessageFormat from 'intl-messageformat';-import type {Catalog, Locale, MessagesByLocale, Overrides} from './types';-import enSource from '../../locales/en.json' with {type: 'json'};+import type {Locale, Overrides, ProviderMessagesByLocale} from './types';+import enCatalog from './generated-locales/en.generated';import {warnOnce, __resetDevWarnings} from '../utils/devWarning';-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@@ -75,7 +73,7 @@ export function resolveLocaleChain(locale: Locale): Locale[] {function getLookup(locale: Locale,- messages: MessagesByLocale,+ messages: ProviderMessagesByLocale,overrides?: Overrides,): Record<string, string> {const lookup: Record<string, string> = {};@@ -95,8 +93,10 @@ function getLookup(for (const tag of chain) {if (messages[tag]) {for (const [key, value] of Object.entries(messages[tag])) {- if (lookup[key] === undefined && value?.defaultMessage !== null) {- lookup[key] = value?.defaultMessage;+ const message =+ typeof value === 'string' ? value : value?.defaultMessage;+ if (lookup[key] === undefined && message != null) {+ lookup[key] = message;}}}@@ -107,13 +107,13 @@ function getLookup(export function getResolve(locale: Locale,- messages: MessagesByLocale,+ messages: ProviderMessagesByLocale,overrides?: Overrides,) {const lookup = getLookup(locale, messages, overrides);return (key: string, values: Record<string, unknown> | undefined) => {- const result = lookup[key] ?? EN_CATALOG[key]?.defaultMessage;+ const result = lookup[key] ?? enCatalog[key];if (result === undefined) {// Fires ONLY when a key is missing from every source including the// shipped `en` catalog — a real bug (typo, stale catalog, deleted key).diff --git a/packages/core/src/i18n/types.ts b/packages/core/src/i18n/types.tsindex 6da7726e50..6df89c5cc8 100644--- a/packages/core/src/i18n/types.ts+++ b/packages/core/src/i18n/types.ts@@ -40,11 +40,22 @@ export interface MessageEntry {export type Catalog = Record<string, MessageEntry>;/**- * A map of BCP 47 tags to catalogs. Passed as `messages` on- * `<InternationalizationProvider>`.+ * A generated runtime catalog. Unlike the authoring `Catalog`, it contains+ * only the ICU messages used by applications and no translator metadata.+ */+export type RuntimeCatalog = Readonly<Record<string, string>>;++/**+ * The original rich-catalog map retained for context consumers.*/export type MessagesByLocale = Record<Locale, Catalog>;+/**+ * Catalog input accepted by `<InternationalizationProvider>`. Each locale can+ * use either the rich authoring shape or a generated runtime string map.+ */+export type ProviderMessagesByLocale = Record<Locale, Catalog | RuntimeCatalog>;+/*** Sparse per-locale overrides applied on top of the shipped defaults.* Only the keys the consumer cares to override need to be listed.diff --git a/packages/core/src/i18n/useTranslator.test.tsx b/packages/core/src/i18n/useTranslator.test.tsxindex d70082b39e..11144066be 100644--- a/packages/core/src/i18n/useTranslator.test.tsx+++ b/packages/core/src/i18n/useTranslator.test.tsx@@ -12,18 +12,26 @@*/import {describe, it, expect, vi, beforeEach} from 'vitest';-import {useState} from 'react';+import {use, useState} from 'react';import {render, screen, fireEvent, renderHook} from '@testing-library/react';import {useTranslator, type TranslatorFn} from './useTranslator';import {InternationalizationProvider} from './InternationalizationProvider';+import {InternationalizationContext} from './InternationalizationContext';import {__resetForTests} from './resolve';-import type {MessagesByLocale, Overrides} from './types';+import type {+ MessagesByLocale,+ Overrides,+ ProviderMessagesByLocale,+} from './types';// Module scope: the provider memoizes on prop identity, so inline object// literals would hand back a fresh context value on every render.const FR_MESSAGES: MessagesByLocale = {fr: {'@astryx.pagination.next': {defaultMessage: 'Page suivante'}},};+const FR_RUNTIME_MESSAGES: ProviderMessagesByLocale = {+ fr: {'@astryx.pagination.next': 'Page suivante compacte'},+};const FR_OVERRIDES: Overrides = {fr: {'@astryx.pagination.next': 'Suivant'},};@@ -68,6 +76,31 @@ describe('useTranslator — resolution', () => {expect(result.current('@astryx.pagination.next')).toBe('Page suivante');});+ it('accepts a generated runtime catalog and preserves the rich context shape', () => {+ const {result} = renderHook(+ () => ({+ context: use(InternationalizationContext),+ translate: useTranslator(),+ }),+ {+ wrapper: ({children}) => (+ <InternationalizationProvider+ locale="fr"+ messages={FR_RUNTIME_MESSAGES}>+ {children}+ </InternationalizationProvider>+ ),+ },+ );++ expect(result.current.translate('@astryx.pagination.next')).toBe(+ 'Page suivante compacte',+ );+ expect(+ result.current.context.messages.fr['@astryx.pagination.next'],+ ).toEqual({defaultMessage: 'Page suivante compacte'});+ });+it('lets a provider override beat the provider catalog', () => {const {result} = renderHook(() => useTranslator(), {wrapper: ({children}) => (diff --git a/scripts/generate-i18n-runtime.mjs b/scripts/generate-i18n-runtime.mjsnew file mode 100644index 0000000000..d405a269cd--- /dev/null+++ b/scripts/generate-i18n-runtime.mjs@@ -0,0 +1,190 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * Generates the compact string-map catalogs shipped to runtime consumers.+ *+ * packages/core/locales/*.json remain the canonical Crowdin sources and keep+ * translator descriptions. Each generated module exports only the+ * key-to-defaultMessage map used at runtime.+ */++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {createPseudoCatalog} from '../packages/core/scripts/build-pseudo-locale.mjs';++const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));+const REPO_ROOT = path.resolve(SCRIPT_DIR, '..');+const SOURCE_LOCALES_DIR = path.join(REPO_ROOT, 'packages', 'core', 'locales');+const GENERATED_LOCALES_DIR = path.join(+ REPO_ROOT,+ 'packages',+ 'core',+ 'src',+ 'i18n',+ 'generated-locales',+);+const EN_FILE = 'en.json';+const PSEUDO_FILE = 'pseudo.json';++function readJson(file) {+ return JSON.parse(fs.readFileSync(file, 'utf8'));+}++function validateEntry(key, entry) {+ if (+ entry === null ||+ typeof entry !== 'object' ||+ Array.isArray(entry) ||+ typeof entry.defaultMessage !== 'string'+ ) {+ throw new Error(`${key}: missing string "defaultMessage"`);+ }+}++/** Reduce a rich authoring catalog to the strings used at runtime. */+export function createRuntimeCatalog(sourceCatalog) {+ return Object.fromEntries(+ Object.entries(sourceCatalog).map(([key, entry]) => {+ validateEntry(key, entry);+ return [key, entry.defaultMessage];+ }),+ );+}++export function createRuntimeCatalogs(sourceCatalogs) {+ const runtimeCatalogs = Object.fromEntries(+ Object.entries(sourceCatalogs).map(([file, catalog]) => [+ file,+ createRuntimeCatalog(catalog),+ ]),+ );+ const english = sourceCatalogs[EN_FILE];+ if (!english) throw new Error(`Missing source catalog: ${EN_FILE}`);+ runtimeCatalogs[PSEUDO_FILE] = createRuntimeCatalog(+ createPseudoCatalog(english),+ );+ return runtimeCatalogs;+}++export function getGeneratedModuleName(sourceFile) {+ if (!sourceFile.endsWith('.json')) {+ throw new Error(`Expected a JSON locale filename: ${sourceFile}`);+ }+ return `${sourceFile.slice(0, -'.json'.length)}.generated.ts`;+}++function getGeneratedModulePath(sourceFile) {+ return path.join(GENERATED_LOCALES_DIR, getGeneratedModuleName(sourceFile));+}++export async function renderRuntimeCatalogModule(runtimeCatalog, sourceFile) {+ const {format, resolveConfig} = await import('prettier');+ const outputFile = getGeneratedModulePath(sourceFile);+ const sourceDescription =+ sourceFile === PSEUDO_FILE+ ? 'the pseudo-localization projection of packages/core/locales/en.json'+ : `packages/core/locales/${sourceFile}`;+ const source = `// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n/**\n * @generated by scripts/generate-i18n-runtime.mjs from ${sourceDescription}.\n * Translator descriptions remain in the authored JSON catalogs and must not be copied here.\n * Do not edit by hand. Run \`pnpm generate:i18n-runtime\` instead.\n */\n\nconst runtimeCatalog: Readonly<Record<string, string>> = ${JSON.stringify(runtimeCatalog)};\n\nexport default runtimeCatalog;\n`;+ const prettierConfig = await resolveConfig(outputFile);+ return format(source, {...prettierConfig, filepath: outputFile});+}++function readSourceCatalogs() {+ return Object.fromEntries(+ fs+ .readdirSync(SOURCE_LOCALES_DIR, {withFileTypes: true})+ .filter(+ entry =>+ entry.isFile() &&+ entry.name.endsWith('.json') &&+ entry.name !== PSEUDO_FILE,+ )+ .map(entry => [+ entry.name,+ readJson(path.join(SOURCE_LOCALES_DIR, entry.name)),+ ])+ .sort(([left], [right]) => left.localeCompare(right)),+ );+}++function writeIfChanged(file, content) {+ if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === content) {+ return false;+ }+ fs.writeFileSync(file, content);+ return true;+}++function removeStaleModules(expectedFiles) {+ if (!fs.existsSync(GENERATED_LOCALES_DIR)) return 0;+ let removed = 0;+ for (const entry of fs.readdirSync(GENERATED_LOCALES_DIR, {+ withFileTypes: true,+ })) {+ if (+ entry.isFile() &&+ entry.name.endsWith('.generated.ts') &&+ !expectedFiles.has(entry.name)+ ) {+ fs.rmSync(path.join(GENERATED_LOCALES_DIR, entry.name));+ removed += 1;+ }+ }+ return removed;+}++export async function generateRuntimeCatalogs({check = false} = {}) {+ const runtimeCatalogs = createRuntimeCatalogs(readSourceCatalogs());++ if (check) {+ console.log(+ `✓ ${Object.keys(runtimeCatalogs).length} authored locale catalogs produce metadata-free runtime maps`,+ );+ return;+ }++ fs.mkdirSync(GENERATED_LOCALES_DIR, {recursive: true});+ const expectedFiles = new Set(+ Object.keys(runtimeCatalogs).map(getGeneratedModuleName),+ );+ const removed = removeStaleModules(expectedFiles);+ let changed = 0;+ for (const [file, catalog] of Object.entries(runtimeCatalogs)) {+ const output = await renderRuntimeCatalogModule(catalog, file);+ if (writeIfChanged(getGeneratedModulePath(file), output)) changed += 1;+ }++ console.log(+ `Generated ${Object.keys(runtimeCatalogs).length} runtime locale modules ` ++ `(${changed} changed, ${removed} stale removed)`,+ );+}++async function main() {+ const args = process.argv.slice(2);+ await generateRuntimeCatalogs({check: args.includes('--check')});+}++function isDirectExecution() {+ if (!process.argv[1]) return false;+ try {+ return (+ fs.realpathSync(process.argv[1]) ===+ fs.realpathSync(fileURLToPath(import.meta.url))+ );+ } catch {+ return false;+ }+}++if (isDirectExecution()) {+ try {+ await main();+ } catch (error) {+ if (!process.argv.slice(2).includes('--best-effort')) throw error;+ const message = error instanceof Error ? error.message : String(error);+ console.warn(`Could not generate runtime locale catalogs: ${message}`);+ }+}diff --git a/scripts/generate-i18n-runtime.test.mjs b/scripts/generate-i18n-runtime.test.mjsnew file mode 100644index 0000000000..727096658f--- /dev/null+++ b/scripts/generate-i18n-runtime.test.mjs@@ -0,0 +1,122 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {spawnSync} from 'node:child_process';+import {mkdtempSync, rmSync, symlinkSync} from 'node:fs';+import {tmpdir} from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {describe, expect, it} from 'vitest';+import {+ createRuntimeCatalog,+ createRuntimeCatalogs,+ getGeneratedModuleName,+ renderRuntimeCatalogModule,+} from './generate-i18n-runtime.mjs';++const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));++describe('generator CLI', () => {+ it('runs when invoked through a symlinked repository path', () => {+ const temp = mkdtempSync(path.join(tmpdir(), 'astryx-i18n-cli-'));+ const linkedRepo = path.join(temp, 'repo');+ symlinkSync(REPO_ROOT, linkedRepo, 'dir');+ try {+ const result = spawnSync(+ process.execPath,+ [path.join(linkedRepo, 'scripts/generate-i18n-runtime.mjs'), '--check'],+ {cwd: linkedRepo, encoding: 'utf8'},+ );+ expect(result.status, result.stderr).toBe(0);+ expect(result.stdout).toContain('authored locale catalogs produce');+ } finally {+ rmSync(temp, {recursive: true, force: true});+ }+ });+});++describe('createRuntimeCatalog', () => {+ it('keeps runtime messages and drops translator metadata', () => {+ const runtimeCatalog = createRuntimeCatalog({+ '@astryx.button.submit': {+ defaultMessage: 'Submit',+ description: 'Visible label for the primary submit button.',+ },+ '@astryx.pagination.page': {+ defaultMessage: 'Page {page, number}',+ description: 'Accessible page label.',+ screenshot: 'translator-only-context.png',+ },+ });++ expect(runtimeCatalog).toEqual({+ '@astryx.button.submit': 'Submit',+ '@astryx.pagination.page': 'Page {page, number}',+ });+ expect(JSON.stringify(runtimeCatalog)).not.toContain('description');+ expect(JSON.stringify(runtimeCatalog)).not.toContain('translator-only');+ });++ it('rejects entries without a runtime message', () => {+ expect(() =>+ createRuntimeCatalog({+ '@astryx.button.submit': {description: 'Translator context only.'},+ }),+ ).toThrow('missing string "defaultMessage"');+ });+});++describe('createRuntimeCatalogs', () => {+ it('uses the string-map shape for real and pseudo locales', () => {+ const catalogs = createRuntimeCatalogs({+ 'en.json': {+ '@astryx.button.submit': {+ defaultMessage: 'Submit',+ description: 'Visible submit label.',+ },+ },+ 'fr-FR.json': {+ '@astryx.button.submit': {+ defaultMessage: 'Envoyer',+ description: 'Visible submit label.',+ },+ },+ });++ expect(Object.keys(catalogs)).toEqual([+ 'en.json',+ 'fr-FR.json',+ 'pseudo.json',+ ]);+ expect(catalogs['fr-FR.json']['@astryx.button.submit']).toBe('Envoyer');+ expect(catalogs['pseudo.json']['@astryx.button.submit']).toBe('⟦Šúƀɱíţ⟧');+ expect(JSON.stringify(catalogs)).not.toContain('description');+ });+});++describe('generated module names', () => {+ it('places generated modules beside the i18n runtime with an explicit suffix', () => {+ expect(getGeneratedModuleName('fr-FR.json')).toBe('fr-FR.generated.ts');+ expect(getGeneratedModuleName('pseudo.json')).toBe('pseudo.generated.ts');+ });++ it('rejects non-JSON source filenames', () => {+ expect(() => getGeneratedModuleName('fr-FR.ts')).toThrow(+ 'Expected a JSON locale filename',+ );+ });+});++describe('renderRuntimeCatalogModule', () => {+ it('emits a default-exported string map tied to its rich source', async () => {+ const output = await renderRuntimeCatalogModule(+ {'@astryx.button.submit': 'Submit'},+ 'fr-FR.json',+ );++ expect(output).toContain('const runtimeCatalog');+ expect(output).toContain('export default runtimeCatalog');+ expect(output).toContain('packages/core/locales/fr-FR.json');+ expect(output).toContain("'@astryx.button.submit': 'Submit'");+ expect(output).not.toContain('defaultMessage');+ });+});diff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex 255e624512..cc97ac95b7 100644--- a/scripts/sync-exports.js+++ b/scripts/sync-exports.js@@ -89,12 +89,15 @@ 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.+ // Rich authoring catalogs keep their existing JSON paths. Generated string+ // maps are additive runtime imports for applications that want no translator+ // metadata in their bundles.'./locales/*.json': './locales/*.json',+ './locales/*.generated.js': {+ source: './src/i18n/generated-locales/*.generated.ts',+ types: './dist/i18n/generated-locales/*.generated.d.ts',+ default: './dist/i18n/generated-locales/*.generated.js',+ },};/** Nested modules backed by an index.ts entry point. */