diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 8854d75a0..40033f62e 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -46,6 +46,16 @@ "getting-started/updating-react-email" ] }, + { + "group": "Guides", + "pages": [ + { + "group": "Internationalization", + "icon": "earth-americas", + "pages": ["guides/internationalization/react-intl"] + } + ] + }, { "group": "Components", "pages": [ diff --git a/apps/docs/guides/internationalization/react-intl.mdx b/apps/docs/guides/internationalization/react-intl.mdx new file mode 100644 index 000000000..8af2a4488 --- /dev/null +++ b/apps/docs/guides/internationalization/react-intl.mdx @@ -0,0 +1,299 @@ +--- +title: 'React Intl' +sidebarTitle: 'React Intl' +description: 'Integrating React Email with React Intl' +'og:image': 'https://react.email/static/covers/react-email.png' +--- + +React Email supports [React Intl](https://formatjs.github.io/react-intl/) for internationalization. + +This guide shows how to convert an English React Email template to support multiple locales. + +## Prerequisites + +To get the most out of this guide, you’ll need to: + +- [Set up React Email](/getting-started/automatic-setup) +- [Install React Intl](https://formatjs.github.io/docs/getting-started/installation) + + + ```bash npm + npm i -S react-intl + ``` + + ```bash bun + bun add react-intl + ``` + + ```bash yarn + yarn add react-intl + ``` + + ```bash pnpm + pnpm add react-intl + ``` + + + +This guide will use the following email template as a base. + +```tsx emails/welcome/index.tsx +interface WelcomeEmailProps { + name: string; +} + +function WelcomeEmail({ + name, +}: WelcomeEmailProps) { + return ( + + + Welcome to Acme + + + +
+ + Welcome to Acme + + + Hi {name} + + + Thanks for signing up! We're excited to have you on board. + + +
+ + If you have any questions, reply to this email. We're here to help! + +
+ + + + + ); +} + +WelcomeEmail.PreviewProps = { + name: 'John Lennon', +}; +``` + +## Internationalization with React Intl + +React Intl is a library for internationalization and localization that provides a way to format messages in different languages. + +### 1. Create messages for each locale + +For each locale, create a new JSON file containing the content of the email in that locale. + + + +```json emails/welcome/en.json +{ + "header": "Welcome to Acme", + "hi": "Hi", + "thanks": "Thanks for signing up! We're excited to have you on board.", + "get-started": "Get Started", + "questions": "If you have any questions, reply to this email. We're here to help!" +} +``` + +```json emails/welcome/es.json +{ + "header": "Bienvenido a Acme", + "hi": "Hola", + "thanks": "Gracias por registrarte! Estamos emocionados de tenerte en la plataforma.", + "get-started": "Comenzar", + "questions": "Si tienes alguna pregunta, responde a este correo electrónico. Estamos aquí para ayudarte!" +} +``` + +```json emails/welcome/pt.json +{ + "header": "Bem-vindo ao Acme", + "hi": "Olá", + "thanks": "Obrigado por se inscrever! Estamos ansiosos para te receber na plataforma.", + "get-started": "Começar", + "questions": "Se você tiver alguma dúvida, responda a este e-mail. Estamos aqui para ajudar!" +} +``` + + + +Alternatively, you can add locale-specific messages in the email file. + + + +```tsx +const messages = { + en: { + header: 'Welcome to Acme', + hi: 'Hi', + thanks: 'Thanks for signing up! We\'re excited to have you on board.', + 'get-started': 'Get Started', + questions: 'If you have any questions, reply to this email. We\'re here to help!', + }, + es: { + header: 'Bienvenido a Acme', + hi: 'Hola', + thanks: 'Gracias por registrarte! Estamos emocionados de tenerte en la plataforma.', + 'get-started': 'Comenzar', + questions: 'Si tienes alguna pregunta, responde a este correo electrónico. Estamos aquí para ayudarte!', + }, + pt: { + header: 'Bem-vindo ao Acme', + hi: 'Olá', + thanks: 'Obrigado por se inscrever! Estamos ansiosos para te receber na plataforma.', + 'get-started': 'Começar', + questions: 'Se você tiver alguma dúvida, responda a este e-mail. Estamos aqui para ajudar!', + }, +}; +``` + + + +### 2. Update the email props + +Add the `locale` prop to the email template, interface, and test data. + +```tsx +interface WelcomeEmailProps { + name: string; +// [!code ++] + locale: 'en' | 'es' | 'pt'; +} + +function WelcomeEmail({ + name, +// [!code ++] + locale, +}: WelcomeEmailProps) { + return ( + ... + ); +} + +WelcomeEmail.PreviewProps = { + name: 'John Lennon', +// [!code ++] + locale: 'en', +}; +``` + + +### 3. Update the email template + +In the email template, remove the hardcoded content and use `createIntl` to format the email message strings. + +```tsx +// [!code ++] +import { createIntl } from 'react-intl'; + +interface WelcomeEmailProps { + name: string; + locale: 'en' | 'es' | 'pt'; +} + +// [!code --] +function WelcomeEmail({ +// [!code ++] +async function WelcomeEmail({ + name, + locale, +}: WelcomeEmailProps) { +// [!code ++:4] + const { formatMessage } = createIntl({ + messages: await import(`emails/welcome/${locale}.json`), // if using locale-specific files + locale, + }); + + return ( + + +// [!code --] + Welcome to Acme +// [!code ++] + {formatMessage({ id: 'header' })} + + + +
+ +// [!code --] + Welcome to Acme +// [!code ++] + {formatMessage({ id: 'header' })} + + +// [!code --] + Hi {name} +// [!code ++] + {formatMessage({ id: 'hi' })} {name} + + +// [!code --] + Thanks for signing up! We're excited to have you on board. +// [!code ++] + {formatMessage({ id: 'thanks' })} + + +
+ +// [!code --] + If you have any questions, reply to this email. We're here to help! +// [!code ++] + {formatMessage({ id: 'questions' })} + +
+ + + + + ); +} + +WelcomeEmail.PreviewProps = { + name: 'John Lennon', + locale: 'en', +}; +``` + +### 4. Update any email calls + +When calling the email template, pass the `locale` prop to the email component. + +## Try it yourself + + + + See the full source code. + + + See the full source code. + +