Jak implementovat internacionalizaci v aplikaci Next.js, která používá App Router

Jak se svět stává stále více globalizovaným, stále důležitější je, aby weboví vývojáři vytvářeli aplikace, které dokážou vyhovět uživatelům z různých zemí a kultur. Jedním z klíčových způsobů, jak toho dosáhnout, je internacionalizace (i18n), která vám umožňuje přizpůsobit vaši aplikaci různým jazykům, měnám a formátům dat.

V tomto článku si ukážeme, jak přidat internacionalizaci do vaší React Next.js aplikace, včetně server-side renderingu. TL;DR: Kompletní příklad najdete zde.

Tento průvodce je určen pro aplikace Next.js, které používají App Router.
Pokud používáte Pages Router, podívejte se místo toho na tento průvodce.

Krok 1: Nainstalujte knihovnu i18n

Abychom implementovali internacionalizaci ve vaší aplikaci Next.js, nejprve si vybereme knihovnu i18n. Existuje několik populárních knihoven, včetně next-intl. V tomto příkladu však budeme používat TacoTranslate.

TacoTranslate automaticky překládá vaše řetězce do libovolného jazyka pomocí špičkové umělé inteligence a osvobozuje vás od únavné správy JSON souborů.

Nainstalujme jej pomocí npm ve vašem terminálu:

npm install tacotranslate

Krok 2: Vytvořte si bezplatný účet TacoTranslate

Nyní, když máte modul nainstalovaný, je čas vytvořit účet TacoTranslate, překladový projekt a příslušné API klíče. Vytvořte si účet zde. Je to zdarma a nevyžaduje zadání platební karty.

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na kartu API klíčů. Vytvořte jeden read klíč a jeden read/write klíč. Uložíme je jako proměnné prostředí. read klíč nazýváme public, a read/write klíč je secret. Například je můžete přidat do souboru .env v kořenovém adresáři vašeho projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Určitě nikdy neprozrazujte tajný read/write API klíč do produkčního prostředí na straně klienta.

Přidáme také dvě další proměnné prostředí: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód náhradní lokality (fallback). V tomto příkladu jej nastavíme na en pro angličtinu.
• TACOTRANSLATE_ORIGIN: “složka”, kde budou vaše řetězce uloženy, například URL vaší webové stránky. Přečtěte si více o originách zde.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Krok 3: Nastavení TacoTranslate

Pro integraci TacoTranslate s vaší aplikací budete muset vytvořit klienta pomocí dříve uvedených API klíčů. Například vytvořte soubor s názvem /tacotranslate-client.js.

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY,
	projectLocale:
		process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Brzy automaticky nastavíme TACOTRANSLATE_API_KEY a TACOTRANSLATE_PROJECT_LOCALE.

Vytvoření klienta v samostatném souboru usnadňuje jeho opětovné použití později. getLocales je pouze pomocná funkce s vestavěným ošetřením chyb. Nyní vytvořte soubor s názvem /app/[locale]/tacotranslate.tsx, kde implementujeme poskytovatele TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Všimněte si 'use client';, což znamená, že se jedná o klientskou komponentu.

Nyní, když je poskytovatel kontextu připraven k použití, vytvořte soubor pojmenovaný /app/[locale]/layout.tsx, který je kořenovým layoutem v naší aplikaci. Všimněte si, že tato cesta má složku využívající Dynamic Routes, kde [locale] je dynamický parametr.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

První věc, které si zde všimnete, je, že používáme náš parametr Dynamic Route [locale] k načítání překladů pro tento jazyk. Navíc generateStaticParams zajišťuje, že všechny kódy locale, které jste pro svůj projekt aktivovali, jsou předrenderovány.

Pojďme nyní vytvořit naši první stránku! Vytvořte soubor s názvem /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Všimněte si proměnné revalidate, která říká Next.js, aby stránku znovu sestavil po 60 sekundách a udržoval vaše překlady aktuální.

Krok 4: Implementace server-side renderování

TacoTranslate podporuje vykreslování na straně serveru. To výrazně zlepšuje uživatelský zážitek tím, že zobrazuje přeložený obsah okamžitě, místo aby se nejprve objevil záblesk nepřeloženého obsahu. Navíc můžeme na klientovi vynechat síťové požadavky, protože už máme překlady potřebné pro stránku, kterou uživatel právě prohlíží.

Pro nastavení vykreslování na straně serveru vytvořte nebo upravte /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			client: tacoTranslateClient,
			isProduction:
				process.env.TACOTRANSLATE_ENV === 'production' ||
				process.env.VERCEL_ENV === 'production' ||
				(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
					process.env.NODE_ENV === 'production'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Upravte kontrolu isProduction tak, aby vyhovovala vašemu nastavení. Pokud je true, TacoTranslate zobrazí veřejný API klíč. Pokud jsme v lokálním, testovacím, nebo staging prostředí (isProduction is false), použijeme tajný read/write API klíč, aby bylo zajištěno, že nové řetězce budou odeslány k překladu.

Aby směrování a přesměrování fungovalo podle očekávání, budeme muset vytvořit soubor s názvem /middleware.ts. Pomocí Middleware můžeme přesměrovat uživatele na stránky zobrazené v jejich preferovaném jazyce.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Ujistěte se, že nastavíte matcher v souladu s dokumentací Next.js k middleware.

Na klientské straně můžete upravit cookie locale tak, aby se změnil preferovaný jazyk uživatele. Prosím podívejte se na úplný ukázkový kód pro nápady, jak to udělat!

Krok 5: Nasadit a otestovat!

Hotovo! Vaše React aplikace bude nyní automaticky překládána, kdykoli přidáte jakékoli řetězce do komponenty Translate. Všimněte si, že pouze prostředí, která mají u API klíče oprávnění read/write, budou moci vytvářet nové řetězce k překladu. Doporučujeme mít uzavřené a zabezpečené stagingové prostředí, kde můžete otestovat svou produkční aplikaci s takovým API klíčem a přidávat nové řetězce před jejím spuštěním. Tím se zabrání komukoli komukoli ukrást váš tajný API klíč a potenciálně nafouknout váš projekt překladu přidáváním nových, nesouvisejících řetězců.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!