Next.js with App Router
Follow the below instructions to learn to implement localization to your Next.js App Router app with Tolgee.
In this example we'll store language in cookies, which is a simple to implement, but is not ideal for SEO. If you want a more robust solution with language in url, see App router with next-intl
Prerequisites
- An existing Next.js project.
- An existing project on Tolgee platform with at least 2 languages. This guide uses English (en) and Czech (cs).
- Add localization keys and translations for both the languages. This guide uses the key name
hello_world
. - API key of your Tolgee project.
Install the required packages
To implement localization to your app, you need to install the @tolgee/react
package:
npm install @tolgee/react
Use @tolgee/react
version 5.30.0
and higher
Folder structure
The folder structure of your project should resemble the following:
├── .env.development.local # ignored by git
├── next.config.js
├── messages
│ ├── en.json
│ └── cs.json
└── src
├── tolgee
│ ├── shared.ts
│ ├── language.ts
│ ├── client.tsx
│ └── server.tsx
└── app
├── layout.tsx
└── page.tsx
Set up your environment
Create the .env.development.local
file if it does not exist. You will store the Tolgee credentials securely in this file.
Paste the following in the newly created file. Replace <your api key>
with your Tolgee API key.
NEXT_PUBLIC_TOLGEE_API_KEY=<your api key>
NEXT_PUBLIC_TOLGEE_API_URL=https://app.tolgee.io
Save exported data
Create an messages
folder in the root of your project directory, if it does not already exists. Move the exported localization json files to the messages
folder.
Set up Tolgee
You need to set up Tolgee for both the client and the server. You can create shared configuration that can be used for both client and server.
Shared configuration
In your tolgee/shared.ts
file, add the following code.
import { DevTools, Tolgee, FormatSimple } from '@tolgee/web';
const apiKey = process.env.NEXT_PUBLIC_TOLGEE_API_KEY;
const apiUrl = process.env.NEXT_PUBLIC_TOLGEE_API_URL;
export const ALL_LANGUAGES = ['en', 'cs'];
export const DEFAULT_LANGUAGE = 'en';
export async function getStaticData(
languages: string[],
namespaces: string[] = ['']
) {
const result: Record<string, any> = {};
for (const lang of languages) {
for (const namespace of namespaces) {
if (namespace) {
result[`${lang}:${namespace}`] = (
await import(`../../messages/${namespace}/${lang}.json`)
).default;
} else {
result[lang] = (await import(`../../messages/${lang}.json`)).default;
}
}
}
return result;
}
export function TolgeeBase() {
return Tolgee()
.use(FormatSimple())
// replace with .use(FormatIcu()) for rendering plurals, foramatted numbers, etc.
.use(DevTools())
.updateDefaults({
apiKey,
apiUrl,
});
}
Client configutation
The client configuration is very similar to the Pages Router set up. It serves the purpose of translating client components and also enables the in-context functionality for server-rendered components.
'use client';
import { TolgeeBase } from './shared';
import { TolgeeProvider, TolgeeStaticData } from '@tolgee/react';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';
type Props = {
language: string;
staticData: TolgeeStaticData;
children: React.ReactNode;
};
const tolgee = TolgeeBase().init();
export const TolgeeNextProvider = ({
language,
staticData,
children,
}: Props) => {
const router = useRouter();
useEffect(() => {
const { unsubscribe } = tolgee.on('permanentChange', () => {
router.refresh();
});
return () => unsubscribe();
}, [tolgee, router]);
return (
<TolgeeProvider
tolgee={tolgee}
options={{ useSuspense: false }}
fallback="Loading"
ssr={{ language, staticData }}
>
{children}
</TolgeeProvider>
);
};
Storing language in cookies
To store user language create file language.ts
, important part here is the "use server"
directive, so we can call setLanguage
method from frontend as server action.
'use server';
import { detectLanguageFromHeaders } from '@tolgee/react/server';
import { cookies, headers } from 'next/headers';
import { ALL_LANGUAGES, DEFAULT_LANGUAGE } from './shared';
const LANGUAGE_COOKIE = 'NEXT_LOCALE';
export async function setLanguage(locale: string) {
const cookieStore = cookies();
cookieStore.set(LANGUAGE_COOKIE, locale, {
maxAge: 1000 * 60 * 60 * 24 * 365, // one year in milisecods
});
}
export async function getLanguage() {
const cookieStore = cookies();
const locale = cookieStore.get(LANGUAGE_COOKIE)?.value;
if (locale && ALL_LANGUAGES.includes(locale)) {
return locale;
}
// try to detect language from headers or use default
const detected = detectLanguageFromHeaders(headers(), ALL_LANGUAGES);
return detected || DEFAULT_LANGUAGE;
}
Server configuration
Your app will utilize the React server cache for sharing Tolgee instance across components in a single render. This allows the app to use the Tolgee instance anywhere in the server components.
One important difference from the client setup is the utilization of fullKeyEncode
. fullKeyEncode
ensures that translations rendered on the server are correctly picked up and interactive for in-context mode.
import { TolgeeBase, ALL_LANGUAGES, getStaticData } from './shared';
import { createServerInstance } from '@tolgee/react/server';
import { getLanguage } from './language';
export const { getTolgee, getTranslate, T } = createServerInstance({
getLocale: getLanguage,
createTolgee: async (locale) =>
TolgeeBase().init({
// including all locales
// on server we are not concerned about bundle size
staticData: await getStaticData(ALL_LANGUAGES),
observerOptions: {
fullKeyEncode: true,
},
language: locale,
fetch: async (input, init) =>
fetch(input, { ...init, next: { revalidate: 0 } }),
}),
});
Use the TolgeeNextProvider
The next step is to wrap the children with the TolgeeNextProvider
. Update the layout.tsx
file with the following code:
import { ReactNode } from 'react';
import { TolgeeNextProvider } from '@/tolgee/client';
import { getStaticData } from '@/tolgee/shared';
import { getLanguage } from '@/tolgee/language';
import './style.css';
type Props = {
children: ReactNode;
params: { locale: string };
};
export default async function LocaleLayout({ children }: Props) {
const locale = await getLanguage();
// it's important you provide all data which are needed for initial render
// so current language and also fallback languages + necessary namespaces
const staticData = await getStaticData([locale]);
return (
<html lang={locale}>
<body>
<TolgeeNextProvider language={locale} staticData={staticData}>
{children}
</TolgeeNextProvider>
</body>
</html>
);
}
The above code loads relevant locale available on the server and pass it to the client component through props.
Make sure you are not using export const dynamic = 'force-static'
on your pages, as that makes it impossible to use cookies (more info).
Localizing Server components
Now that everything is setup, you can use the getTranslate
function to render the translated text. Since this is a server component, you use getTranslate
instead of the useTranslate
hook.
import { getTranslate } from '@/tolgee/server';
export default async function IndexPage() {
// because this is server component, use `getTranslate`
// not useTranslate from '@tolgee/react'
const t = await getTranslate();
return (
<main>
<h1>{t('hello_world')}</h1>
</main>
);
}
If everything is set up correctly, you could use in-context translation. Press and holde the alt
(or option
) key, and click hello_world
. This will open the in-context pop-up window.
Localizing Client components
For client components, you can use the useTranslate
hook or the t-component
.
'use client';
import { useTranslate } from '@tolgee/react';
export const ExampleClientComponent = () => {
const { t } = useTranslate();
return (
<section>
<span>{t('example-key-in-client-component')}</span>
</section>
);
};
Make sure to use @/tolgee/server
in server components and @tolgee/react
in client components.
Switching Languages
For switching languages use setLanguage
server action from language.ts
, which will just update our cookie.
'use client';
import React from 'react';
import { useTolgee } from '@tolgee/react';
import { setLanguage } from '@/tolgee/language';
export const LangSelector: React.FC = () => {
const tolgee = useTolgee(['language']);
const language = tolgee.getLanguage();
function onSelectChange(e) {
setLanguage(e.target.value);
}
return (
<select onChange={onSelectChange} value={language}>
<option value="en">🇬🇧 English</option>
<option value="cs">🇨🇿 Česky</option>
</select>
);
};
Limitations of Server Components
Although in-context translation works with server components, there are some limitations compared to client components. The Tolgee cache on the server is separate. This prevents Tolgee from automatically changing the translation when creating a screenshot (unlike with client components, which swap the content if you've modified it in a dialog).
Furthermore, if you're using the Tolgee browser plugin, it won't affect the server's transition to dev mode. As a result, only the client switches, leaving server components non-editable in this mode.