i18n

Install react-intl

npm i react-intl

Setup the translations

To begin the localization setup, start by creating a /messages folder within the /public directory of your Next.js application. Within this /messages folder, you'll organize your translation files for each language. As an example, you can create your initial translation file, en.json, to kickstart the localization process.

Important Note:

When integrating translations into your project, it is crucial to follow the conventions outlined below. These conventions are designed to facilitate effective management by the localization team:

1. Language separation: Each language translation should be stored in separate files. For instance, you can have files such as en.json, fr.json, and br.json, each corresponding to a specific language.

2. Translation ID prefix: All translation identifiers must begin with the admin/ prefix. This prefix helps maintain consistency and organization within your translation files, making it easier to manage and reference specific translations.

By following these conventions, you can ensure a standardized and structured approach to managing translations in your project.

{
  "admin/<your-app>.<your-string>": "..."
}

Fetch the messages from the folder

After successfully adding the translation messages, the next step is to fetch and utilize them within your application. A helpful tip is to create a custom hook in your project specifically designed to handle this functionality. By implementing a dedicated hook, you can streamline the process of retrieving and displaying the appropriate translations in your application.

import { useMemo } from 'react'
import useSWR from 'swr'
import { useAdmin } from '@vtex/raccoon-next'
import { fetcher } from '../util' /* example fetcher : const fetcher = (...args: any[]) => fetch(...args).then(res => res.json()) */
 
export function useI18n(locale: string) {
  // gets the locale provided by the admin-shell
  const { locale = 'en-US' } = useAdmin()
  // locales have the format [lang]-[countryCode]
  const [lang] = useMemo(() => locale.split('-'), [locale])
  // Use SWR (or normal fetch) to get the messages by country code.
  const { data: messages, error } = useSWR(
    countryCode ? { url: `/messages/${lang}.json` } : null,
    fetcher
  )
 
  return {
    locale,
    countryCode,
    messages,
    loading: !messages && !error,
    error,
  }
}

Configure the root of the application

Next, you will need to add the IntlProvider component within the _app.js file. Remember to pass the locale and messages obtained from the useI18n hook as props to the IntlProvider. Additionally, ensure that you provide the locale to the I18nProvider to incorporate the default translations available in the design system. Here's an example of how your modified _app.js file should look like:

import type { AppProps } from 'next/app'
import { connect, bootstrap } from '@vtex/raccoon-next'
import { ThemeProvider, I18nProvider } from '@vtex/admin-ui'
import { IntlProvider } from 'react-intl'
 
import { useI18n } from '../hooks/use-i18n'
 
connect()
 
function MyApp({ Component, pageProps }: AppProps) {
  const { locale, messages, loading } = useI18n(locale)
 
  if (loading) return null
 
  return (
    <IntlProvider messages={messages} locale={locale}>
      <ThemeProvider>
        <I18nProvider locale={locale}>
          <Component {...pageProps} />
        </I18nProvider>
      </ThemeProvider>
    </IntlProvider>
  )
}
 
export default bootstrap(MyApp)