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

Jak se svět stále více globalizuje, je pro webové vývojáře čím dál důležitější vytvářet 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 data.

V tomto článku prozkoumáme, jak přidat internacionalizaci do vaší React Next.js aplikace se server-side renderingem. 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 raději na tento průvodce.

Krok 1: Nainstalujte knihovnu i18n

Pro implementaci internacionalizace ve vaší aplikaci Next.js nejprve vybereme i18n knihovnu. 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 jakéhokoli jazyka za použití špičkové umělé inteligence a zbavuje vás tak nudné správy JSON souborů.

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

npm install tacotranslate

Krok 2: Vytvořte si zdarma účet na TacoTranslate

Nyní, když máte modul nainstalovaný, je čas vytvořit svůj účet TacoTranslate, překladatelský projekt a související API klíče. Vytvořte si zde účet. 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 záložku API klíče. 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é další dvě proměnné prostředí: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí náhradní kód lokality. 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šeho webu. Přečtěte si více o původech zde.

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

Krok 3: Nastavení TacoTranslate

Chcete-li integrovat TacoTranslate do své aplikace, budete potřebovat vytvořit klienta pomocí dříve získaný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 budeme automaticky definovat 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 zpracování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ž označuje, že se jedná o klientskou komponentu.

S připraveným poskytovatelem kontextu nyní vytvořte soubor s názvem /app/[locale]/layout.tsx, což je kořenové rozvržení v naší aplikaci. Všimněte si, že tato cesta obsahuje 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, kterou je třeba zde poznamenat, je, že používáme náš parametr Dynamic Route [locale] k získávání překladů pro daný jazyk. Dále generateStaticParams zajišťuje, že všechny kódy jazyků, které jste pro svůj projekt aktivovali, jsou předrenderovány.

Nyní postavme 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 vytvořil po 60 sekundách a udržoval vaše překlady aktuální.

Krok 4: Implementace server-side renderování

TacoTranslate podporuje server-side rendering. To výrazně zlepšuje uživatelský zážitek tím, že okamžitě zobrazuje přeložený obsah místo nejprve záblesku nepřeloženého obsahu. Navíc můžeme na klientovi přeskočit síťové požadavky, protože již máme překlady potřebné pro stránku, kterou uživatel právě prohlíží.

Pro nastavení server-side renderingu 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 uživatele přesměrovat 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 jste nastavili matcher v souladu s dokumentací Next.js Middleware.

Na klientovi můžete upravit cookie locale pro změnu preferovaného jazyka uživatele. Pro inspiraci, jak to udělat, si prosím prohlédněte kompletní ukázkový kód!

Krok 5: Nasazení a testování!

Jsme hotovi! Vaše Reactová aplikace bude nyní automaticky překládána, kdykoli přidáte jakýkoli text do komponenty Translate. Vezměte prosím na vědomí, že pouze prostředí s oprávněním read/write k API klíči budou schopna vytvářet nové texty k překladu. Doporučujeme mít uzavřené a zabezpečené testovací prostředí, kde můžete vaši produkční aplikaci testovat s takovým API klíčem a přidávat nové texty před nasazením. Tím zabráníte komukoli ukrást váš tajný API klíč a potenciálně nafouknout váš překladatelský projekt přidáváním nových, nesouvisejících textů.

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!