Next-intl library integration in NextJS - Step-by-Step Execution

Concept Flow - Next-intl library integration

Install next-intl

↓

Create messages files

↓

Wrap app with NextIntlProvider

↓

Use useTranslations hook in components

↓

Render translated text

↓

Switch locale to update UI

This flow shows how to add next-intl: install, add messages, wrap app, use translations, and update UI on locale change.

Execution Sample

NextJS

import {NextIntlProvider, useTranslations} from 'next-intl';

export default function App({Component, pageProps}) {
  return <NextIntlProvider messages={pageProps.messages} locale={pageProps.locale}>
    <Component {...pageProps} />
  </NextIntlProvider>;
}

function Greeting() {
  const t = useTranslations('Greeting');
  return <p>{t('hello')}</p>;
}

This code wraps the app with NextIntlProvider and uses useTranslations hook to show translated 'hello' text.

Execution Table

Step	Action	Input/State	Output/Result
1	Install next-intl package	npm install next-intl	Package ready to use
2	Create messages files	en.json: {"Greeting": {"hello": "Hello!"}}	Messages loaded for locales
3	Wrap app with NextIntlProvider	pageProps.locale='en', pageProps.messages=en.json	Context provides translations
4	Call useTranslations('Greeting') in Greeting component	Context with messages	Returns function t(key)
5	Call t('hello')	Key='hello'	Returns 'Hello!' string
6	Render <p>{t('hello')}</p>	Text 'Hello!'	Paragraph with 'Hello!' shown
7	Change locale to 'fr' with messages	fr.json: {"Greeting": {"hello": "Bonjour!"}}	UI updates to show 'Bonjour!'
8	Call t('hello') again	Key='hello', locale='fr'	Returns 'Bonjour!' string
9	Render updated <p>{t('hello')}</p>	Text 'Bonjour!'	Paragraph updates to 'Bonjour!'
10	End of flow	N/A	App shows translated greeting based on locale

💡 Flow ends after rendering translated text and updating UI on locale change

Variable Tracker

Variable	Start	After Step 3	After Step 5	After Step 7	Final
pageProps.locale	undefined	'en'	'en'	'fr'	'fr'
pageProps.messages	undefined	{"Greeting":{"hello":"Hello!"}}	{"Greeting":{"hello":"Hello!"}}	{"Greeting":{"hello":"Bonjour!"}}	{"Greeting":{"hello":"Bonjour!"}}
t	undefined	function	function returning 'Hello!'	function returning 'Bonjour!'	function returning 'Bonjour!'
Rendered Text	none	none	'Hello!'	'Bonjour!'	'Bonjour!'

Key Moments - 3 Insights

Why do we need to wrap the app with NextIntlProvider?

NextIntlProvider provides the translation context to all components. Without it, useTranslations hook cannot find messages (see step 3 in execution_table).

How does changing the locale update the displayed text?

Changing locale updates pageProps.locale and pageProps.messages, so useTranslations returns translations for the new locale (see steps 7-9). React re-renders with new text.

What does useTranslations('Greeting') return?

It returns a function t(key) that looks up the translation for the given key in the 'Greeting' namespace (see step 4).

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of 'Rendered Text' after step 5?

A undefined

B 'Bonjour!'

C 'Hello!'

D An error

💡 Hint

Check the 'Rendered Text' variable in variable_tracker after step 5

At which step does the UI update to show the French greeting?

A Step 5

B Step 9

C Step 3

D Step 7

💡 Hint

Look at execution_table rows where rendering happens with 'Bonjour!' text

If we remove NextIntlProvider wrapping, what happens when useTranslations is called?

A It throws an error or returns undefined

B It returns translations from default locale

C It works normally

D It shows untranslated keys

💡 Hint

Refer to key_moments about why NextIntlProvider is needed (step 3)

Concept Snapshot

Next-intl integration steps:
1. Install next-intl package
2. Create locale message JSON files
3. Wrap app with <NextIntlProvider> passing locale and messages
4. Use useTranslations(namespace) hook in components
5. Call t(key) to get translated text
6. Change locale to update UI translations automatically

Full Transcript

This visual execution shows how to integrate the next-intl library in a Next.js app. First, install the package and create JSON files with translations for each locale. Then wrap your app component with NextIntlProvider, passing the current locale and messages. Inside components, use the useTranslations hook with a namespace to get a function t that returns translated strings by key. Rendering t('hello') shows the translated greeting. When the locale changes, the provider updates messages and the UI re-renders with new translations. Key points include the need for NextIntlProvider to provide context and how useTranslations depends on it. This step-by-step trace helps beginners see how state changes flow through the app to update displayed text.

Practice

1. What is the main purpose of the NextIntlProvider component in a Next.js app using next-intl?

easy

A. To fetch data from an API

B. To provide translation messages and locale context to the app

C. To handle routing between pages

D. To style components with CSS

Solution

1. Step 1: Understand the role of NextIntlProvider

   The NextIntlProvider wraps the app and supplies translation messages and locale information to all child components.

2. Step 2: Compare with other options

   Fetching data, routing, and styling are unrelated to NextIntlProvider's purpose.

3. Final Answer:

   To provide translation messages and locale context to the app -> Option B

4. Quick Check:

   NextIntlProvider = translation context provider [OK]

Hint: NextIntlProvider always wraps your app to share translations [OK]

Common Mistakes:

• Confusing NextIntlProvider with data fetching
• Thinking it handles routing or styling
• Not realizing it shares locale and messages

2. Which of the following is the correct way to import and use the useTranslations hook in a Next.js component?

easy

A. import { useTranslations } from 'next-intl'; const t = useTranslations('common');

B. import useTranslations from 'next-intl'; const t = useTranslations('common');

C. import { useTranslations } from 'next-intl'; const t = useTranslations();

D. import { useTranslation } from 'next-intl'; const t = useTranslation('common');

Solution

1. Step 1: Check correct import syntax

   The hook is named useTranslations and imported with curly braces from 'next-intl'.

2. Step 2: Verify usage with namespace

   It requires a namespace string like 'common' to get translations from that section.

3. Final Answer:

   import { useTranslations } from 'next-intl'; const t = useTranslations('common'); -> Option A

4. Quick Check:

   Correct import and call with namespace = import { useTranslations } from 'next-intl'; const t = useTranslations('common'); [OK]

Hint: Always import with braces and pass namespace string [OK]

Common Mistakes:

• Importing without braces
• Calling useTranslations without arguments
• Using wrong hook name useTranslation

3. Given this component using next-intl:

import { useTranslations } from 'next-intl';

export default function Greeting() {
  const t = useTranslations('greeting');
  return <h1>{t('hello')}</h1>;
}

If the messages for locale 'en' are { greeting: { hello: 'Hello, friend!' } }, what will be rendered?

medium

A. An error because 'hello' key is missing

B. <h1>greeting.hello</h1>

C. <h1>Hello, friend!</h1>

D. <h1>Hello</h1>

Solution

1. Step 1: Understand useTranslations usage

   The hook useTranslations('greeting') accesses the 'greeting' namespace in messages.

2. Step 2: Check message key 'hello'

   The key 'hello' inside 'greeting' is 'Hello, friend!'. So t('hello') returns that string.

3. Final Answer:

   <h1>Hello, friend!</h1> -> Option C

4. Quick Check:

   Namespace + key returns correct text = <h1>Hello, friend!</h1> [OK]

Hint: Namespace + key in messages gives displayed text [OK]

Common Mistakes:

• Expecting raw keys instead of translated text
• Assuming missing keys cause errors
• Confusing namespace with key

4. You wrote this code in a Next.js page:

import { NextIntlProvider } from 'next-intl';

export default function Page({ messages }) {
  return (
    <NextIntlProvider messages={messages} locale="en">
      <h1>Welcome</h1>
    </NextIntlProvider>
  );
}

But you get an error: "messages is undefined". What is the likely cause?

medium

A. You forgot to load and pass messages as a prop to the Page component

B. NextIntlProvider does not accept a messages prop

C. Locale must be passed as a number, not a string

D. You must import useTranslations instead of NextIntlProvider

Solution

1. Step 1: Check messages prop usage

   The NextIntlProvider requires a valid messages object passed as a prop.

2. Step 2: Identify cause of undefined

   If messages is undefined, it means the parent or data loader did not supply it properly.

3. Final Answer:

   You forgot to load and pass messages as a prop to the Page component -> Option A

4. Quick Check:

   Missing messages prop causes undefined error [OK]

Hint: Always load and pass messages before using NextIntlProvider [OK]

Common Mistakes:

• Thinking NextIntlProvider doesn't need messages
• Passing locale as number instead of string
• Confusing hooks with provider component

5. You want to support English and Spanish in your Next.js app using next-intl. You have message files:

locales/en.json
locales/es.json

How should you structure your app/layout.tsx to load messages dynamically and provide translations to all pages?

hard

A. Load messages inside each page component instead of layout

B. Import both JSON files statically and pass both to NextIntlProvider at once

C. Use useTranslations in layout to load messages and pass to children

D. Use async function to load messages based on locale, then wrap children with NextIntlProvider passing loaded messages and locale

Solution

1. Step 1: Understand dynamic message loading

   To support multiple locales, load messages dynamically based on the current locale in an async layout or provider.

2. Step 2: Wrap app with NextIntlProvider

   Pass the loaded messages and locale to NextIntlProvider wrapping all children so translations are available app-wide.

3. Final Answer:

   Use async function to load messages based on locale, then wrap children with NextIntlProvider passing loaded messages and locale -> Option D

4. Quick Check:

   Dynamic loading + provider wrapping = Use async function to load messages based on locale, then wrap children with NextIntlProvider passing loaded messages and locale [OK]

Hint: Load messages async by locale, wrap app with NextIntlProvider [OK]

Common Mistakes:

• Importing all locales at once statically
• Loading messages inside pages instead of layout
• Using useTranslations to load messages