{"id":70452,"date":"2023-12-11T13:03:18","date_gmt":"2023-12-11T12:03:18","guid":{"rendered":"https:\/\/phrase.com\/?p=70452"},"modified":"2024-11-04T17:58:43","modified_gmt":"2024-11-04T16:58:43","slug":"next-js-l10n-format-js-react-intl","status":"publish","type":"post","link":"https:\/\/phrase.com\/blog\/posts\/next-js-l10n-format-js-react-intl\/","title":{"rendered":"Next.js Localization with Format.JS\/react-intl"},"content":{"rendered":"\n
\n\n\t\n\t
\n\t\t
\n\t\t\t

Next.js<\/a> Pages Router localization has become a streamlined feature of the leading full-stack React framework since the advent of Next.js 10, which brought us helpful localized routing capabilities.<\/p>\n

Adding the robust react-intl\/Format.JS<\/a> i18n library takes this a step further, offering a comprehensive solution that includes production-grade translation message management, along with refined date and number formatting.<\/p>\n

What sets react-intl\/Format.JS apart from other i18n libraries is its advanced translation message extraction and compilation, allowing our apps to scale gracefully and efficiently. In this tutorial, we explore the ins and outs of localizing Next.js Pages Router apps with react-intl\/Format.JS.<\/p>\n

<\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n\n

\n\t
\n\t\t\t\t\t
\n\t\t\t\t\"String\t\t\t<\/div>\n\t\t\t\t
\n\t\t\t

Phrase Strings<\/p>\n

Take your web or mobile app global without any hassle<\/p>\n

\n

Adapt your software, website, or video game for global audiences with the leanest and most realiable software localization platform.<\/p>\n

Explore Phrase Strings<\/a><\/p>\n<\/div>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n\n

\n\n\t\n\t
\n\t\t
\n\t\t\t

\ud83d\udca1\u00a0Internationalization (i18n) and localization (l10n) allow us to make our apps available in different languages and to different regions, often for more profit. If you\u2019re new to i18n and l10n, check out our guide to internationalization<\/a>.<\/p>\n

\ud83d\uddd2\ufe0f\u00a0Format.JS is a set of ICU-compliant JavaScript i18n libraries. react-intl extends Format.JS with handy React components and hooks. In this article, where we focus on React\/Next.js, we will use the terms \u201creact-intl\u201d and \u201cFormat.JS\u201d interchangeably.<\/p>\n

\ud83d\udd17 This article is focused on the Next.js Pages Router. If you\u2019re working with the App Router, check out our Deep Dive into Next.js App Router Localization with next-intl<\/a>\u2014and if you prefer working with the Pages Router and the popular i18next library, our Step-by-Step Guide to Next.js Internationalization<\/a> has you covered.<\/p>\n

Our demo app<\/h2>\n

We will use a simple blog to demo the i18n in this guide. Here\u2019s what the app looks like before localization.<\/p>\n

\"The<\/p>\n

\"Single<\/p>\n

\ud83d\udce3 Shoutout \u00bb Thanks to Scotty G<\/a> for creating the fun Star Wars lorem ipsum generator, Forcem Ipsum<\/a>, which we\u2019ve used for our mock content.<\/p>\n

After spinning up a Next.js app with the Pages Router, TypeScript, and Tailwind, we created\/modified the following files to build the demo:<\/p>\n

<\/p>\n

<\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n

.\n\u2514\u2500\u2500 pages\n    \u251c\u2500\u2500 components\n    \u2502   \u2514\u2500\u2500 Layout.tsx  # Wraps our pages\n    \u251c\u2500\u2500 data\n    \u2502   \u2514\u2500\u2500 posts.ts    # Mock blog post data\n    \u251c\u2500\u2500 posts\n    \u2502   \u251c\u2500\u2500 [slug].tsx  # Single blog post\n    \u2502   \u2514\u2500\u2500 index.tsx   # Blog post listing\n    \u2514\u2500\u2500 index.tsx       # Home page<\/code><\/span>Code language:<\/span> plaintext<\/span> (<\/span>plaintext<\/span>)<\/span><\/small><\/pre>\n\n\n
\n\n\t\n\t
\n\t\t
\n\t\t\t
It\u2019s all bread-and-butter Next.js, and we will get into the details of these files as we internationalize. Let\u2019s get to it.<\/p>\n
Package versions used<\/h2>\n
Here are the relevant NPM packages we\u2019ve used in this tutorial.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Package<\/td>\nVersion<\/td>\nNotes<\/td>\n<\/tr>\n<\/thead>\n
typescript<\/td>\n5.2.<\/td>\n<\/td>\n<\/tr>\n
next<\/td>\n14,9<\/td>\n<\/td>\n<\/tr>\n
react<\/td>\n18.2<\/td>\n<\/td>\n<\/tr>\n
react-intl<\/td>\n6.5<\/td>\nUsed for i18n<\/td>\n<\/tr>\n
@formatjs\/cli<\/td>\n6.2<\/td>\nUsed for message extraction and compilation<\/td>\n<\/tr>\n
babel-plugin-formatjs<\/td>\n10.5<\/td>\nUsed for automatic message ID injection<\/td>\n<\/tr>\n
nookies<\/td>\n2.5<\/td>\nUsed for setting the Next.js locale cookie<\/td>\n<\/tr>\n
accept-language-parser<\/td>\n1.5<\/td>\nUsed for custom locale auto-detection<\/td>\n<\/tr>\n
rtl-detect<\/td>\n1.1<\/td>\nUsed for right-to-left (rtl) locale detection<\/td>\n<\/tr>\n
tailwindcss<\/td>\n3.3<\/td>\nUsed for styling (and out of the scope of this tutorial)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
How do I localize my Pages Router app with react-intl?<\/h2>\n
Next.js Pages Router apps need to manage server-side rendering (SSR) using getStaticProps()<\/code> and static site generation (SSG) with getStaticPaths()<\/code>. With that in mind, here are the basic steps to localizing a Next.js Pages router with react-intl:<\/p>\n
    \n
  1. Configure built-in Next.js i18n routing.<\/li>\n
  2. Install and configure react-intl.<\/li>\n
  3. Localize page\/component strings using react-intl.<\/li>\n
  4. Extract translation messages from our codebase using the Format.JS CLI.<\/li>\n
  5. Translate messages into supported languages.<\/li>\n
  6. Load translation messages on the server using getStaticProps()<\/code>.<\/li>\n
  7. Format dates and numbers using react-intl.<\/li>\n<\/ol>\n
    In the following sections, we will cover these steps and more, including compiling messages for production, writing custom middleware for locale auto-detection, and adding a language selector for our site visitors.<\/p>\n
    Let\u2019s work through in one step at a time.<\/p>\n
    How do I configure the built-in Next.js i18n routing?<\/h2>\n
    Recent versions of Next.js come with localized routing out-of-the-box. This automatically adds our supported locales to routes, e.g. \/fr\/posts<\/code> for our posts page in French.<\/p>\n
    Let\u2019s see how this works by adding it to our demo. We will support English (USA) and Arabic (Egypt) here. Feel free to use any locales you want.<\/p>\n
    A note on locales<\/h3>\n
    Locales typically use IETF BCP 47 language tags<\/a>, like en<\/code> for English, fr<\/code> for French, and es<\/code> for Spanish. Adding a region with the ISO Alpha-2 code (e.g., BH<\/code> for Bahrain, CN<\/code> for China, and US<\/code> for the United States) is recommended for accurate date and number localization. So a complete locale might look like en-US<\/code> for American English or zh-CN<\/code> for Chinese in China.<\/p>\n
    \ud83d\udd17 Explore more language tags on Wikipedia<\/a> and find country codes through the ISO’s search tool<\/a>.<\/p>\n
    To enable localized routing, we need to add an i18n<\/code> section to our next.config.js<\/code>:<\/p>\n
    <\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n
    \/** @type {import('next').NextConfig} *\/\nconst nextConfig = {\n  reactStrictMode: true,\n+ i18n: {<\/span>\n+   locales: [\"en-US\", \"ar-EG\"], \/\/ required<\/span>\n+   defaultLocale: \"en-US\",      \/\/ required<\/span>\n+ },<\/span>\n};\n\nmodule.exports = nextConfig;<\/code><\/span>Code language:<\/span> Diff<\/span> (<\/span>diff<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n\n\t\n\t
    \n\t\t
    \n\t\t\t
    \u270b Both locales<\/code> and defaultLocale<\/code> are required in Next.js. If either is missing or invalid, Next.js will trigger an error during development server runs and production builds.<\/p>\n
    Just with that, Next.js creates an \/ar-EG<\/code> prefix for all our routes. We started with these routes in our app:<\/p>\n\n\n\n\n\n\n\n
    Route<\/td>\nDescription<\/td>\n<\/tr>\n<\/thead>\n
    \/<\/code><\/td>\nhome page<\/td>\n<\/tr>\n
    \/posts<\/code><\/td>\nblog post index<\/td>\n<\/tr>\n
    \/posts\/foo-bar<\/code><\/td>\nsingle blog post<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    After adding the above i18n config, we now have the following routes:<\/p>\n\n\n\n\n\n\n\n\n\n\n
    Route<\/td>\nActive locale<\/td>\nDescription<\/td>\n<\/tr>\n<\/thead>\n
    \/<\/code><\/td>\nEnglish (en-US)<\/td>\nhome page<\/td>\n<\/tr>\n
    \/ar-EG<\/code><\/td>\nArabic (ar-EG)<\/td>\nhome page<\/td>\n<\/tr>\n
    \/posts<\/code><\/td>\nEnglish (en-US)<\/td>\nblog post index<\/td>\n<\/tr>\n
    \/ar-EG\/posts<\/code><\/td>\nArabic (ar-EG)<\/td>\nblog post index<\/td>\n<\/tr>\n
    \/posts\/foo-bar<\/code><\/td>\nEnglish (en-US)<\/td>\nsingle blog post<\/td>\n<\/tr>\n
    \/ar-EG\/posts\/foo-bar<\/code><\/td>\nArabic (ar-EG)<\/td>\nsingle blog post<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    For every locale included in the locales<\/code> array of our config, a corresponding route prefix is created. The default route (en-US<\/code> in our case) doesn’t receive any prefix.<\/p>\n
    \ud83d\uddd2\ufe0f\u00a0It’s worth noting, though, that the Next.js documentation<\/a> offers a workaround for redirecting unprefixed URLs, e.g. \/<\/code>, to prefixed URLs, such as \/en-US<\/code>. This approach, however, comes with its own set of challenges, such as the need to juggle a placeholder default<\/code> locale in the supported locales list, and potential errors during production builds when Next.js attempts to build pages with this placeholder default<\/code> locale.<\/p>\n
    Moving on, Next.js also provides access to the active locale through its router object. Let\u2019s make use of this in our single post page to show the translated blog post.<\/p>\n
    Our hard-coded mock data is already localized:<\/p>\n
    <\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n
    \/\/ data\/posts.ts<\/span>\n\nimport<\/span> type<\/span> { Post } from<\/span> \"@\/types\"<\/span>;\n\nexport<\/span> const<\/span> posts: Post[] = [\n  {\n    slug: \"marching-into-detention-area\"<\/span>,\n    date: \"2023-11-10\"<\/span>,\n    translations: {\n      \"en-US\"<\/span>: {\n         title: \"Marching into the...\"<\/span>,\n         content: \"What an incredible...\"<\/span>,\n      },\n      \"ar-EG\"<\/span>: {\n         title: \"\u0625\u0646 \u0627\u0644\u0632\u062d\u0641 \u0625\u0644\u0649 \u0645\u0646\u0637\u0642\u0629 \u0627\u0644\u0627\u062d\u062a\u062c\u0627\u0632 \u0644\u0645...\"<\/span>,\n         content: \"\u064a\u0627 \u0644\u0647\u0627 \u0645\u0646 \u0631\u0627\u0626\u062d\u0629 \u0645\u0630\u0647\u0644\u0629 \u0627\u0643\u062a\u0634\u0641\u062a\u0647\u0627...\"<\/span>,\n      },\n    },\n  },\n  \/\/ ...<\/span>\n]<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n\n\t\n\t
    \n\t\t
    \n\t\t\t
    Using the locale<\/span> route param from Next.js, we can refine this data and show the appropriate content for the active locale.<\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n
    \/\/ pages\/posts\/[slug].tsx\n\nimport Layout from \"@\/components\/Layout\";\nimport { posts } from \"@\/data\/posts\";\nimport type { Post } from \"@\/types\";\nimport type {\n  GetStaticPaths,\n  GetStaticProps,\n  GetStaticPropsContext,\n} from \"next\";\nimport Link from \"next\/link\";\nimport { useRouter } from \"next\/router\";\n\ntype SinglePostProps = {\n  post: Post;\n};\n\nexport const getStaticPaths: GetStaticPaths<{\n  slug: string;\n}> = () => {\n  return {\n    paths: posts.map((post) => ({\n      params: { slug: post.slug },\n    })),\n    fallback: true,\n  };\n};\n\nexport const getStaticProps = (async ({\n  params,\n}: GetStaticPropsContext) => {\n  const post = posts.find(\n    (post) => post.slug === params?.slug,<\/span>\n  );\n\n  if (!post) return { notFound: true };\n\n  return { props: { post } };\n}) satisfies GetStaticProps<SinglePostProps>;\n\nexport default function SinglePost({\n  post,\n}: SinglePostProps) {\n  const router = useRouter();\n\n+ const locale = router.locale!;<\/span>\n+ \/\/ => \"en-US\" when route is \/posts\/foo<\/span>\n+ \/\/ => \"ar-EG\" when route is \/ar-EG\/posts\/foo<\/span>\n\n  if (router.isFallback) {\n    return <div>Loading...<\/div>;\n  }\n\n  return (\n    <Layout>\n      <!-- ... -->\n\n      <!-- We previously hard-coded the locale -->\n-     <h1 className=\"...\">{post.translations[\"en-US\"].title}<\/h1><\/span>\n+     <h1 className=\"...\">{post.translations[locale].title}<\/h1><\/span>\n      <p className=\"...\">{post.date}<\/p>\n      <div className=\"...\">\n-        <p>{post.translations[\"en-US\"].content}<\/p><\/span>\n+        <p>{post.translations[locale].content}<\/p><\/span>\n      <\/div>\n    <\/Layout>\n  );\n}<\/code><\/span>Code language:<\/span> Diff<\/span> (<\/span>diff<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n\n\t\n\t
    \n\t\t
    \n\t\t\t
    With that, we\u2019re showing the post translated to the active locale.<\/p>\n
    \"When<\/p>\n
    \"The<\/p>\n
    On localized dynamic routes and getStaticPaths()<\/h3>\n
    For dynamic routes like [slug].tsx<\/code>, when using fallback: false<\/code> to generate all locale variants during the build, we need to include all<\/em> locales in getStaticPaths()<\/code>:<\/p>\n
    <\/p>\n
     <\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n
    \/\/ pages\/_app.tsx\n\n- import arMessages from \"@\/lang\/compiled\/ar-EG.json\";<\/span>\n- import enMessages from \"@\/lang\/compiled\/en-US.json\";<\/span>\n  import \"@\/styles\/globals.css\";\n  import type { AppProps } from \"next\/app\";\n  import { useRouter } from \"next\/router\";\n  import { useEffect } from \"react\";\n  import { IntlProvider } from \"react-intl\";\n\n- const messages = {<\/span>\n-   \"en-US\": { ...enMessages },<\/span>\n-   \"ar-EG\": { ...arMessages },<\/span>\n- };<\/span>\n\n  export default function App({ Component, pageProps }: AppProps) {\n    const { locale, defaultLocale } = useRouter();\n\n    return (\n      <IntlProvider\n        locale={locale!}\n        defaultLocale={defaultLocale!}\n-       messages={messages[locale as keyof typeof messages]}<\/span>\n+       messages={pageProps.localeMessages}<\/span>\n      >\n        <Component {...pageProps} \/>\n      <\/IntlProvider>\n    );\n  }<\/code><\/span>Code language:<\/span> Diff<\/span> (<\/span>diff<\/span>)<\/span><\/small><\/pre>\n\n
    export<\/span> const<\/span> getStaticPaths: GetStaticPaths = ({\n  locales,\n}: GetStaticPathsContext) => {\n  return<\/span> {\n    paths: locales!.flatMap((locale<\/span><\/span>) =><\/span>\n      posts.map((post<\/span><\/span>) =><\/span> ({\n        params: { slug: post.slug },\n        locale,\n      })),\n    ),\n    fallback: false<\/span>,\n  };\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n\n\t\n\t
    \n\t\t
    \n\t\t\t
    Here, locales<\/code> refers to the array defined in next.config.js<\/code>. However, this approach can slow down our production build due to the large number of page variants (equal to the number of slugs times the number of locales).<\/p>\n
    As an alternative, omitting locale<\/code> only builds variants for the default locale, with fallback: true<\/code> dynamically generating other locale variants on route visits.<\/p>\n
    \ud83d\udd17 Learn more in the official doc, Dynamic Routes and getStaticProps Pages<\/a>.<\/p>\n
    \u270b Be aware that localized routes do not work with pure static site generation<\/a> (SSG), i.e., output: \"export\"<\/code>.<\/p>\n
    Localized links<\/h3>\n
    Next.js automatically localizes <Link><\/code> elements. For example, <Link href=\"\/about\"><\/code> will actually point to \/ar-EG\/about<\/code> when the active locale is ar-EG<\/code>. Additionally, you can switch locales<\/a> by using the locale<\/code> prop on <Link><\/code>. (We will discuss locale switching using the Next.js router a bit later).<\/p>\n
    Automatic locale detection<\/h3>\n
    Next.js automatically detects a user’s locale<\/a> when they visit the home route \/<\/code> by using the HTTP Accept-Language<\/a> header, which reflects the browser and operating system language settings.<\/p>\n
    For instance, if a user with Arabic (Egypt) (ar-EG<\/code>) as their top browser language preference visits \/<\/code>, they will get redirected to \/ar-EG<\/code>. However, this detection isn’t loosely matched; a user with Arabic (Syria) (ar-SY<\/code>) won’t be redirected to \/ar-EG<\/code>, despite Syrians and Egyptians sharing the same written Arabic. We will address this when we tackle custom locale detection later.<\/p>\n
    \ud83e\udd3f Go deeper **with Detecting a User\u2019s Locale in a Web App<\/a>.<\/p>\n
    Localized routes alone don’t fully internationalize an app; managing UI translations, dates, and numbers is also crucial. This is where react-intl comes in.<\/p>\n
    How do I install and configure react-intl in my Next.js Pages Router app?<\/h2>\n
    Installing react-intl is easy enough.<\/p>\n
    <\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n
    npm install react-intl<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n\n\t\n\t
    \n\t\t
    \n\t\t\t
    To make our active locale and translation messages available to our pages and components, we need to wrap them with react-intl\u2019s <IntlProvider><\/span>.<\/p>\n\t\t<\/div>\n\t<\/div>\n<\/div>\n\n\n
    \/\/ pages\/_app.tsx<\/span>\n\nimport<\/span> \"@\/styles\/globals.css\"<\/span>;\nimport<\/span> type<\/span> { AppProps } from<\/span> \"next\/app\"<\/span>;\n\n\/\/ Import IntlProvider<\/span>\nimport<\/span> { IntlProvider } from<\/span> \"react-intl\"<\/span>;\n\n\/\/ Add translations<\/span>\nconst<\/span> messages = {\n  \"en-US\"<\/span>: {\n    hello: \"Hello, World!\"<\/span>,\n  },\n  \"ar-EG\"<\/span>: {\n    hello: \"\u0645\u0631\u062d\u0628\u0627\u064b \u0628\u0627\u0644\u0639\u0627\u0644\u0645!\"<\/span>,\n  },\n};\n\nexport<\/span> default<\/span> function<\/span> App<\/span>({ Component, pageProps }: AppProps<\/span>) <\/span>{\n  const<\/span> { locale, defaultLocale } = useRouter();\n\n  return<\/span> (\n    \/\/ Wrap page component with IntlProvider<\/span>\n    <IntlProvider\n      locale={locale!}\n      defaultLocale={defaultLocale!}\n      messages={messages[locale as<\/span> keyof typeof<\/span> messages]}\n    >\n      <Component {...pageProps} \/>\n    <\/IntlProvider>\n  );\n}<\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n\n\t\n\t
    \n\t\t
    \n\t\t\t
    When configuring <IntlProvider><\/code>:<\/p>\n