Skip to content

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

TypeScript

docs: clarify i18n catalog guidance (#4294)

nynexman4464e8e187c7f3cc
diff --git a/packages/cli/docs/internationalization.doc.mjs b/packages/cli/docs/internationalization.doc.mjs
index 98a2235b15..facec23c84 100644
--- a/packages/cli/docs/internationalization.doc.mjs
+++ b/packages/cli/docs/internationalization.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
title: 'Internationalization',
category: 'guide',
description:
- 'Localize astryx component strings, provide translation catalogs, override default text, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
+ 'Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
sections: [
{
@@ -16,13 +16,13 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale`, and astryx components pick up localized strings automatically.',
+ text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',
},
{
type: 'code',
lang: 'tsx',
label: 'Wrap your app',
- code: `import {InternationalizationProvider} from '@astryxdesign/core';
+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
function App() {
return (
@@ -32,53 +32,56 @@ function App() {
);
}`,
},
+ {
+ type: 'prose',
+ text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',
+ },
{
type: 'code',
lang: 'tsx',
- label: 'Read strings inside a component',
- code: `import {useTranslator} from '@astryxdesign/core';
+ label: 'Load an astryx locale catalog',
+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import fr from '@astryxdesign/core/locales/fr.json';
-function SaveButton() {
- const t = useTranslator();
- return <button>{t('@myapp.actions.save')}</button>;
-}`,
+<InternationalizationProvider locale="fr" messages={{fr}}>
+ <App />
+</InternationalizationProvider>;`,
},
{
type: 'prose',
- text: 'The hook is available to consumer components too, but using it is entirely optional: many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement; the resolver treats every key as an opaque string.',
+ 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`).',
},
{
type: 'prose',
- text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way, since astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
+ text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',
},
],
},
{
- title: 'Providing locale catalogs',
+ title: 'Runtime language swap',
category: 'guide',
content: [
{
type: 'prose',
- text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work: the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
+ text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
},
{
type: 'code',
lang: 'tsx',
- label: 'Add French',
- code: `import {InternationalizationProvider} from '@astryxdesign/core';
-import fr from './locales/astryx/fr.json';
+ label: 'Toggle between locales',
+ code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
-<InternationalizationProvider locale="fr" messages={{fr}}>
+<InternationalizationProvider locale={locale} messages={{fr}}>
+ <Button
+ label={locale === 'en' ? 'Français' : 'English'}
+ onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
+ />
<App />
</InternationalizationProvider>;`,
},
{
type: 'prose',
- text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point: every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
- },
- {
- type: 'prose',
- text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Translations are coordinated through Crowdin — contribute at https://crowdin.com/project/astryx.',
+ text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
},
],
},
@@ -119,7 +122,7 @@ import fr from './locales/astryx/fr.json';
type: 'code',
lang: 'tsx',
label: 'Astryx + react-intl side by side',
- code: `import {InternationalizationProvider} from '@astryxdesign/core';
+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
import {Selector} from '@astryxdesign/core/Selector';
import {Button} from '@astryxdesign/core/Button';
import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
@@ -169,35 +172,56 @@ export default function App() {
},
{
type: 'prose',
- text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
+ text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",
},
],
},
{
- title: 'Runtime language swap',
+ title: 'Using astryx as your i18n library',
category: 'guide',
content: [
{
type: 'prose',
- text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
+ text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",
},
{
type: 'code',
lang: 'tsx',
- label: 'Toggle between locales',
- code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
+ label: 'Translate app strings with astryx',
+ code: `import {Button} from '@astryxdesign/core/Button';
+import {
+ InternationalizationProvider,
+ useTranslator,
+ type Catalog,
+ type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
-<InternationalizationProvider locale={locale} messages={{fr}}>
- <Button
- label={locale === 'en' ? 'Français' : 'English'}
- onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
- />
- <App />
-</InternationalizationProvider>;`,
+const en: Catalog = {
+ '@myapp.actions.save': {defaultMessage: 'Save'},
+};
+
+const fr: Catalog = {
+ '@myapp.actions.save': {defaultMessage: 'Enregistrer'},
+};
+
+const messages: MessagesByLocale = {en, fr};
+
+function SaveButton() {
+ const t = useTranslator();
+ return <Button label={t('@myapp.actions.save')} />;
+}
+
+export default function App() {
+ return (
+ <InternationalizationProvider locale="fr" messages={messages}>
+ <SaveButton />
+ </InternationalizationProvider>
+ );
+}`,
},
{
type: 'prose',
- text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
+ 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`.',
},
],
},
@@ -207,39 +231,57 @@ export default function App() {
content: [
{
type: 'prose',
- text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switching to it in development instantly reveals any astryx string that isn\'t going through the translator, plus any layout that breaks under longer text.',
+ text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
},
{
type: 'code',
lang: 'tsx',
label: 'Turn on pseudo-localization',
- code: `import pseudo from '@astryxdesign/core/locales/pseudo.json';
+ code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import pseudo from '@astryxdesign/core/locales/pseudo.json';
<InternationalizationProvider locale="pseudo" messages={{pseudo}}>
<App />
</InternationalizationProvider>;`,
},
- {
- type: 'prose',
- text: 'Any bare English text you still see on screen is a hardcoded string that needs to be routed through `useTranslator`.',
- },
- {
- type: 'prose',
- text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated; anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
- },
],
},
{
title: 'For contributors',
category: 'guide',
content: [
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Developers',
+ },
+ {
+ type: 'prose',
+ text: 'Astryx component authors read strings with `useTranslator()` rather than hardcoding user-facing text.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'Read an astryx string',
+ code: `import {useTranslator} from '@astryxdesign/core/i18n';
+
+function SaveButton() {
+ const t = useTranslator();
+ return <button>{t('@astryx.actions.save')}</button>;
+}`,
+ },
{
type: 'prose',
text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
},
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Translators',
+ },
{
type: 'prose',
- text: 'Translators: Crowdin is the preferred way to contribute — join a language at https://crowdin.com/project/astryx, translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
+ text: 'Crowdin is the preferred way to contribute — [join a language](https://crowdin.com/project/astryx), translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
},
],
},
diff --git a/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs
new file mode 100644
index 0000000000..e86f460833
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.doc.mjs
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'InternationalizationProvider',
+ name: 'InternationalizationProvider — Shipped Locale',
+ displayName: 'Internationalization Provider — Shipped Locale',
+ description:
+ 'Load a locale catalog shipped by Astryx and re-render InternationalizationProvider with a new locale to update Astryx strings live.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'InternationalizationProvider',
+ 'SegmentedControl',
+ 'Selector',
+ 'Layout',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx
new file mode 100644
index 0000000000..1ceb58193b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import frFR from '@astryxdesign/core/locales/fr-FR.json';
+import {Stack} from '@astryxdesign/core/Layout';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {Selector} from '@astryxdesign/core/Selector';
+
+type Locale = 'en' | 'fr-FR';
+
+export default function InternationalizationProviderShippedLocale() {
+ const [locale, setLocale] = useState<Locale>('en');
+ const [value, setValue] = useState<string | null>(null);
+ return (
+ <InternationalizationProvider locale={locale} messages={{'fr-FR': frFR}}>
+ <Stack direction="vertical" gap={4} hAlign="center">
+ <SegmentedControl
+ label="Language"
+ value={locale}
+ onChange={nextLocale => setLocale(nextLocale as Locale)}
+ size="sm">
+ <SegmentedControlItem value="en" label="EN" />
+ <SegmentedControlItem value="fr-FR" label="FR" />
+ </SegmentedControl>
+ <Selector
+ style={{width: 300}}
+ label="Billing region"
+ options={[
+ {value: 'americas', label: 'Americas'},
+ {value: 'emea', label: 'EMEA'},
+ {value: 'apac', label: 'APAC'},
+ ]}
+ value={value}
+ onChange={setValue}
+ hasClear
+ />
+ </Stack>
+ </InternationalizationProvider>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs
new file mode 100644
index 0000000000..07f3e7752d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'InternationalizationProvider',
+ name: 'InternationalizationProvider — Overrides',
+ displayName: 'Internationalization Provider — Overrides',
+ description:
+ 'Override a small number of Astryx strings without providing a full locale catalog.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['InternationalizationProvider', 'Selector'],
+};
diff --git a/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx
new file mode 100644
index 0000000000..4eb5fe9901
--- /dev/null
+++ b/packages/cli/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx
@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import {Selector} from '@astryxdesign/core/Selector';
+
+export default function InternationalizationProviderOverrides() {
+ const [value, setValue] = useState<string | null>(null);
+ return (
+ <InternationalizationProvider
+ locale="en"
+ overrides={{
+ en: {
+ '@astryx.selector.placeholder': 'Choose...',
+ },
+ }}>
+ <Selector
+ style={{width: 300}}
+ label="Billing region"
+ options={[
+ {value: 'americas', label: 'Americas'},
+ {value: 'emea', label: 'EMEA'},
+ {value: 'apac', label: 'APAC'},
+ ]}
+ value={value}
+ onChange={setValue}
+ hasClear
+ />
+ </InternationalizationProvider>
+ );
+}
diff --git a/packages/core/locales/fr-FR.json b/packages/core/locales/fr-FR.json
index dc889cc340..b02a390f38 100644
--- a/packages/core/locales/fr-FR.json
+++ b/packages/core/locales/fr-FR.json
@@ -6,5 +6,9 @@
"@astryx.pagination.next": {
"defaultMessage": "Aller à la page suivante",
"description": "Aria label for the next-page button."
+ },
+ "@astryx.selector.placeholder": {
+ "defaultMessage": "Sélectionner…",
+ "description": "Placeholder text on an empty Selector trigger button (a dropdown). Imperative verb; trailing `…` is one character. Very short — appears on the button face."
}
}
diff --git a/packages/core/src/i18n/InternationalizationProvider.doc.mjs b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
index da0c5e4c16..631a7d1de2 100644
--- a/packages/core/src/i18n/InternationalizationProvider.doc.mjs
+++ b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
@@ -20,7 +20,29 @@ export const docs = {
],
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.",
+ '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.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use shipped Astryx locale catalogs from `@astryxdesign/core/locales/*` when one exists for your target locale.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use a same-shape local catalog only when Astryx has not shipped that locale yet or you are testing in-progress translations.',
+ },
+ {
+ 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.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',
+ },
+ ],
},
props: [
{
@@ -35,7 +57,7 @@ export const docs = {
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.',
+ '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.',
},
{
name: 'overrides',
@@ -51,6 +73,59 @@ export const docs = {
description: 'Content to render with the internationalization provider.',
},
],
+ examples: [
+ {
+ 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';
+
+export function AppI18n({children}: {children: ReactNode}) {
+ return (
+ <InternationalizationProvider locale="fr-FR" messages={{'fr-FR': frFR}}>
+ {children}
+ </InternationalizationProvider>
+ );
+}`,
+ },
+ {
+ label: 'Override one Astryx string',
+ code: `import type {ReactNode} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+
+export function AppI18n({children}: {children: ReactNode}) {
+ return (
+ <InternationalizationProvider
+ locale="en"
+ overrides={{
+ en: {'@astryx.selector.placeholder': 'Choose...'},
+ }}
+ >
+ {children}
+ </InternationalizationProvider>
+ );
+}`,
+ },
+ {
+ label: 'Provide a local fallback catalog',
+ code: `import type {ReactNode} from 'react';
+import {
+ InternationalizationProvider,
+ type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
+import ptBR from './locales/pt-BR.json';
+
+const messages: MessagesByLocale = {'pt-BR': ptBR};
+
+export function AppI18n({children}: {children: ReactNode}) {
+ return (
+ <InternationalizationProvider locale="pt-BR" messages={messages}>
+ {children}
+ </InternationalizationProvider>
+ );
+}`,
+ },
+ ],
};
/** @type {import('../docs-types').TranslationDoc} */