Ako implementovať internacionalizáciu v Next.js aplikácii, ktorá používa App Router

Keď sa svet stáva stále viac globalizovaným, je pre webových vývojárov čoraz dôležitejšie vytvárať aplikácie, ktoré dokážu osloviť používateľov z rôznych krajín a kultúr. Jedným z kľúčových spôsobov, ako toho dosiahnuť, je internacionalizácia (i18n), ktorá vám umožňuje prispôsobiť vašu aplikáciu rôznym jazykom, menám a formátom dátumu.

V tomto článku preskúmame, ako pridať internacionalizáciu do vašej React Next.js aplikácie s vykresľovaním na strane servera. TL;DR: Pozrite si tu celý príklad.

Tento návod je určený pre aplikácie Next.js, ktoré používajú App Router.
Ak používate Pages Router, pozrite si namiesto toho tento návod.

Krok 1: Nainštalujte knižnicu i18n

Aby sme implementovali internacionalizáciu vo vašej Next.js aplikácii, najprv si vyberieme knižnicu i18n. Existuje niekoľko populárnych knižníc, vrátane next-intl. V tomto príklade však budeme používať TacoTranslate.

TacoTranslate automaticky prekladá vaše reťazce do ľubovoľného jazyka pomocou špičkovej umelej inteligencie a zbavuje vás zdĺhavej správy JSON súborov.

Nainštalujme ho pomocou npm vo vašom termináli:

npm install tacotranslate

Krok 2: Vytvorte si bezplatný účet TacoTranslate

Keď už máte modul nainštalovaný, je čas vytvoriť si účet TacoTranslate, prekladací projekt a súvisiace API kľúče. Vytvorte si účet tu. Je to zadarmo a nevyžaduje zadanie platobnej karty.

V používateľskom rozhraní TacoTranslate vytvorte projekt a prejdite na kartu jeho API kľúčov. Vytvorte jeden read kľúč a jeden read/write kľúč. Uložíme ich ako premenné prostredia. read kľúč je to, čo nazývame public, a read/write kľúč je secret. Napríklad ich môžete pridať do súboru .env v koreňovom adresári vášho projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Dbajte na to, aby ste nikdy neprezradili tajný read/write API kľúč v produkčných prostrediach na strane klienta.

Pridáme tiež ďalšie dve premenné prostredia: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Predvolený kód náhradného jazyka. V tomto príklade ho nastavíme na en pre angličtinu.
• TACOTRANSLATE_ORIGIN: „zložka“, kde budú uložené vaše reťazce, napríklad URL vašej webovej stránky. Viac informácií o originách nájdete tu.

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

Krok 3: Nastavenie TacoTranslate

Aby ste integrovali TacoTranslate do svojej aplikácie, budete musieť vytvoriť klienta s použitím API kľúčov z predchádzajúcej časti. Napríklad vytvorte súbor s názvom /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;

Čoskoro automaticky definujeme TACOTRANSLATE_API_KEY a TACOTRANSLATE_PROJECT_LOCALE.

Vytvorenie klienta v samostatnom súbore uľahčí jeho opätovné použitie neskôr. getLocales je len pomocná funkcia s vstavaným ošetrením chýb. Teraz vytvorte súbor s názvom /app/[locale]/tacotranslate.tsx, kde implementujeme poskytovateľa 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šimnite si 'use client';, čo naznačuje, že ide o komponentu na strane klienta.

Keď je poskytovateľ kontextu teraz pripravený, vytvorte súbor s názvom /app/[locale]/layout.tsx, koreňový layout v našej aplikácii. Všimnite si, že táto cesta obsahuje priečinok využívajúci Dynamic Routes, kde [locale] je dynamický parameter.

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>
	);
}

Prvou vecou, ktorú treba poznamenať, je, že používame náš parameter Dynamic Route [locale] na načítanie prekladov pre daný jazyk. Navyše, generateStaticParams zaisťuje, že všetky kódy lokalít, ktoré ste pre svoj projekt aktivovali, sú predgenerované.

Poďme vytvoriť našu prvú stránku! Vytvorte súbor s názvom /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šimnite si premennú revalidate, ktorá povie Next.js, aby stránku po 60 sekundách znovu zostavil a udržiaval vaše preklady aktuálne.

Krok 4: Implementácia vykresľovania na strane servera

TacoTranslate podporuje renderovanie na strane servera. To výrazne zlepšuje používateľský zážitok tým, že preložený obsah zobrazuje okamžite, namiesto toho, aby sa najprv objavil záblesk nepreloženého obsahu. Okrem toho môžeme vynechať sieťové požiadavky na strane klienta, pretože už máme preklady, ktoré potrebujeme pre stránku, ktorú používateľ práve prehliada.

Na nastavenie renderovania na strane servera vytvorte alebo 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};
};

Prispôsobte kontrolu isProduction vašej konfigurácii. Ak je true, TacoTranslate zobrazí verejný API kľúč. Ak sme v lokálnom, testovacom alebo staging prostredí (isProduction is false), použijeme tajný API kľúč read/write, aby sa nové reťazce odoslali na preklad.

Aby smerovanie a presmerovanie fungovali podľa očakávania, budeme musieť vytvoriť súbor s názvom /middleware.ts. Pomocou Middleware, môžeme presmerovať používateľov na stránky v ich preferovanom jazyku.

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);
}

Uistite sa, že nastavíte matcher v súlade s dokumentáciou Next.js o middleware.

Na klientskej strane môžete upraviť cookie locale tak, aby sa zmenil preferovaný jazyk používateľa. Pozrite si úplný ukážkový kód pre nápady, ako to urobiť!

Krok 5: Nasadiť a otestovať!

Hotovo! Vaša React aplikácia bude teraz automaticky prekladaná, keď pridáte akékoľvek reťazce do komponentu Translate. Majte na pamäti, že len prostredia s oprávneniami read/write na API kľúči budú môcť vytvárať nové reťazce určené na preklad. Odporúčame mať uzavreté a zabezpečené stagingové prostredie, kde môžete otestovať produkčnú aplikáciu s takýmto API kľúčom a pred nasadením pridávať nové reťazce. Týmto zabránite, aby niekto niekto ukradol váš tajný API kľúč a tým potenciálne nezaplnil váš prekladový projekt pridávaním nových, nesúvisiacich reťazcov.

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!