Skip to main content

Going Global: Internationalization (i18n)

Strato Admin has first-class support for multiple languages using ICU MessageFormat — the same standard used by most professional localization platforms. In this chapter, we will add French to StratoShop.

How Strato i18n Works​

Translation is handled by the icuI18nProvider, which wraps your message catalogs and exposes them to the framework. Strato Admin ships with pre-translated system strings (button labels, error messages, etc.) in English and French. You only need to translate your own app-specific strings — field labels, page titles, and any <Message> components you use.

Step 1: Install the Language Packs​

Terminal
npm install @strato-admin/i18n @strato-admin/language-en @strato-admin/language-fr

Step 2: Configure the i18n Provider​

Update src/App.tsx to set up the provider with both locales:

src/App.tsx
import { Admin } from '@strato-admin/admin';
import { icuI18nProvider } from '@strato-admin/i18n';
import englishMessages from '@strato-admin/language-en';
import frenchMessages from '@strato-admin/language-fr';
import { dataProvider } from '@strato-admin/faker-ecommerce';

const messages = {
  en: englishMessages,
  fr: frenchMessages,
};

const i18nProvider = icuI18nProvider(
  (locale) => messages[locale as keyof typeof messages],
  'en', // default locale
  [
    { locale: 'en', name: 'English' },
    { locale: 'fr', name: 'Français' },
  ],
);

const App = () => (
  <Admin dataProvider={dataProvider} i18nProvider={i18nProvider}>
    {/* ... */}
  </Admin>
);

With two locales configured, a language switcher automatically appears in the top navigation bar. No extra setup needed.

Step 3: Mark Your Strings for Extraction​

String labels you pass as props to Strato components are automatically extracted by the CLI. For example:

<ResourceSchema name="products" label="Products" listTitle="Product Catalog">
  <TextField source="name" label="Product Name" />
  <NumberField source="price" label="Price" />
</ResourceSchema>

For inline translated text (e.g., in a custom dashboard), use the <Message> component:

import { Message } from '@strato-admin/admin';

<Message>Welcome to the StratoShop admin dashboard.</Message>;

Step 4: Extract Strings​

Run the extraction CLI from your project root. It scans your source files and produces a .po file for each locale:

Terminal
npx strato-extract src/ --output locales/

This creates:

locales/
├── en/
│   └── messages.po
└── fr/
    └── messages.po

The English .po file is pre-filled with all the strings found in your source. Open locales/fr/messages.po in a text editor or localization tool (e.g., Poedit, Lokalise) and fill in the msgstr translations.

A typical entry looks like:

msgid "Product Name"
msgstr "Nom du produit"

Step 5: Compile Translations​

After translating, compile the .po files into the JSON format that icuI18nProvider consumes:

Terminal
npx strato-compile locales/

This writes compiled JSON files:

locales/
├── en/
│   └── messages.compiled.json
└── fr/
    └── messages.compiled.json

Step 6: Load Compiled Translations​

Import the compiled files and merge them with the language pack messages:

src/App.tsx
import englishMessages from '@strato-admin/language-en';
import frenchMessages from '@strato-admin/language-fr';
import enAppMessages from '../locales/en/messages.compiled.json';
import frAppMessages from '../locales/fr/messages.compiled.json';

const messages = {
  en: { ...englishMessages, ...enAppMessages },
  fr: { ...frenchMessages, ...frAppMessages },
};

Now, when the user switches to French, all your field labels, page titles, and <Message> components will render in French.

How it Works​

  • Hash-based keys: Strato i18n uses a hash of the English source string as the translation key. This means you never write key strings by hand — the CLI manages the mapping.
  • ICU MessageFormat: Translations support pluralization, gender, and interpolation. For example: "You have {count, plural, one {# order} other {# orders}}.".
  • Lazy loading: The icuI18nProvider function accepts an async getMessages callback, so you can load locale bundles on demand instead of bundling them all up front.

Summary​

In this chapter, we've learned how to:

  • Configure icuI18nProvider with multiple locales to activate the language switcher.
  • Mark app-specific strings for extraction using field props and <Message>.
  • Use the strato-extract and strato-compile CLI tools to build translation catalogs.
  • Merge app translations with the built-in language packs.

Next Steps​

In the final chapter, we will deploy StratoShop to production and discuss testing and next steps.