Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
Internationalization (i18n) in React Email provides a framework for implementing multi-language support within email templates. The system allows developers to create responsive, localized content that adapts to different regional requirements and languages. Sources: skills/react-email/references/I18N.md:7-9, skills/react-email/SKILL.md:244-245
The project officially supports integration with three primary i18n libraries: next-intl, react-i18next, and react-intl (FormatJS). These libraries manage translation messages, locale-specific formatting for dates and currencies, and pluralization. Sources: skills/react-email/references/I18N.md:12-14, skills/react-email/SKILL.md:299
Integration Architecture
The i18n flow begins with passing a locale prop to the top-level email component. The template then uses this locale to initialize a translator or fetch messages from external JSON files. Sources: skills/react-email/references/I18N.md:300-304, skills/react-email/SKILL.md:43-50
This diagram shows how a locale prop triggers the retrieval of translated strings from message files via an i18n library. Sources: skills/react-email/references/I18N.md:44-53, skills/react-email/references/I18N.md:80-86
Supported Libraries
| Library | Best Use Case | Key Features |
|---|---|---|
| next-intl | Next.js applications | Straightforward API, async message importing. |
| react-intl | Complex formatting | Handles plurals, dates, numbers via FormatJS. |
| react-i18next | Non-Next.js apps | High control, namespace loading, backend resources. |
Sources: skills/react-email/references/I18N.md:16-144, skills/react-email/references/I18N.md:146-248
Core Implementation Components
Html Component Configuration
The <Html> component acts as the root wrapper and handles standard accessibility attributes for i18n. Developers must set the lang and dir attributes based on the active locale to ensure correct rendering and screen reader behavior. Sources: skills/react-email/references/COMPONENTS.md:91-99, skills/react-email/SKILL.md:282-286
lang: Defines the language code (e.g., "en", "ar").dir: Sets text direction ("ltr" for Left-to-Right or "rtl" for Right-to-Left).
Sources: skills/react-email/references/COMPONENTS.md:101-103, skills/react-email/references/I18N.md:309-315
Right-to-Left (RTL) Support
Templates support RTL languages like Arabic or Hebrew by checking the locale string. The application logic dynamically assigns the dir attribute to the Html component. Sources: skills/react-email/references/I18N.md:309-315, skills/react-email/TESTS.md:374-386
This flow illustrates the logic used to determine text direction based on the provided locale. Sources: skills/react-email/references/I18N.md:311-315, skills/react-email/TESTS.md:382-386
Message Organization
The system recommends organizing translation strings in JSON files by namespace or template. Sources: skills/react-email/references/I18N.md:251-260
Recommended File Structure
Developers can choose between single-file locale objects or separate files per template:
messages/en.json: Contains all English keys for every email type.messages/en/welcome-email.json: Contains only keys relevant to the welcome template.
Sources: skills/react-email/references/I18N.md:256-276
Translation Key Schema
Using hierarchical, descriptive keys improves maintainability across locales.
Sources: skills/react-email/references/I18N.md:278-294
{
"welcome-email": {
"subject": "Welcome!",
"header": {
"title": "Welcome to Acme",
"subtitle": "We're glad you're here"
},
"cta": {
"primary": "Get Started"
}
}
}
Sources: skills/react-email/references/I18N.md:280-293
Best Practices for Localized Emails
1. Locale Prop Requirement
Always define locale as a required prop in the interface for every email component. This ensures the template has the necessary context for rendering. Sources: skills/react-email/references/I18N.md:300-304
2. Formatting Consistency
Utilize native Intl APIs for locale-specific formatting to maintain consistency in dates, times, and currency. Sources: skills/react-email/references/I18N.md:347-353
- Use
Intl.NumberFormatfor currency. - Use
Intl.DateTimeFormatfor dates.
Sources: skills/react-email/references/I18N.md:386-397
3. Subject Line Localization
Translate email subject lines before sending. Pass the translated string to the email service provider's send method. Sources: skills/react-email/references/I18N.md:337-345
const t = createTranslator({...});
await resend.emails.send({
from: 'Acme <onboarding@resend.dev>',
to: [user.email],
subject: t('subject'), // Translated subject
react: <WelcomeEmail {...props} />
});
Sources: skills/react-email/references/I18N.md:340-345
4. Fallback Handling
Implement catch blocks when importing message files. If a specific locale file is missing, the system should default to a primary language like English. Sources: skills/react-email/references/I18N.md:317-324
Summary
Internationalization in React Email requires a combination of external i18n libraries and proper configuration of structural components like Html. By passing locale props and using absolute JSON message files, developers create emails that are accessible and culturally relevant across global audiences. Sources: skills/react-email/references/I18N.md:7-14, skills/react-email/SKILL.md:282-286