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

Ako sa svet globalizuje, je čoraz dôležitejšie, aby weboví vývojári vytvárali 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 to dosiahnuť, je internacionalizácia (i18n), ktorá vám umožňuje prispôsobiť aplikáciu rôznym jazykom, menám a formátom dátumu.

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

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

Na implementáciu internacionalizácie vo vašej Next.js aplikácii si najprv 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 akéhokoľvek jazyka pomocou špičkovej umelej inteligencie a zbavuje vás únavnej správy JSON súborov.

Nainštalujme ho pomocou npm v termináli:

npm install tacotranslate

Krok 2: Vytvorte si bezplatný účet TacoTranslate

Teraz, keď máte modul nainštalovaný, je čas vytvoriť si účet TacoTranslate, prekladateľský projekt a príslušné API kľúče. Vytvorte si účet tu. Je to zadarmo a nevyžaduje pridanie kreditnej karty.

V používateľskom rozhraní aplikácie TacoTranslate vytvorte projekt a prejdite na kartu API kľúčov. Vytvorte jeden read kľúč a jeden read/write kľúč. Uložíme ich ako premenné prostredia. Kľúč read nazývame public a kľúč read/write 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

Uistite sa, že nikdy neprezradíte tajný API kľúč read/write v produkčných prostrediach na strane klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Predvolený kód záložnej lokality. V tomto príklade ho nastavíme na en pre angličtinu.
• TACOTRANSLATE_ORIGIN: „priečinok“, kde sa budú ukladať vaše reťazce, napríklad URL vašej webovej stránky. Prečítajte si viac o originách 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 pomocou predchádzajúcich API kľúčov. 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 niekoľkými vstavanými ošetreniami 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 znamená, že ide o klientsku komponentu.

Keď je poskytovateľ kontextu pripravený, vytvorte súbor s názvom /app/[locale]/layout.tsx, ktorý je koreňovým rozložením 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>
	);
}

Prvá vec, ktorú treba poznamenať, je, že používame náš parameter Dynamic Route [locale] na načítanie prekladov pre daný jazyk. Okrem toho generateStaticParams zabezpečuje, aby boli vopred vygenerované všetky kódy locale, ktoré máte pre svoj projekt aktivované.

Teraz vytvoríme 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 znovu zostavil po 60 sekundách a udržal vaše preklady aktuálne.

Krok 4: Implementácia renderovania na strane servera

TacoTranslate podporuje renderovanie na serveri. To výrazne zlepšuje používateľský zážitok tým, že okamžite zobrazí preložený obsah, namiesto záblesku nepreloženého obsahu na začiatku. Navyše môžeme na klientskej strane vynechať sieťové požiadavky, pretože už máme preklady, ktoré potrebujeme pre stránku, ktorú používateľ zobrazuje.

Ak chcete nastaviť vykresľovanie 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};
};

Upravte kontrolu isProduction tak, aby vyhovovala vášmu nastaveniu. Ak je true, TacoTranslate sprístupní verejný API kľúč. Ak sa nachádzame v lokálnom, testovacom alebo staging prostredí (isProduction is false), použijeme tajný read/write API kľúč, aby sa nové reťazce odoslali na preklad.

Aby routovanie a presmerovania fungovali podľa očakávaní, budeme musieť vytvoriť súbor s názvom /middleware.ts. Pomocou Middleware, môžeme presmerovať používateľov na stránky zobrazené 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 nakonfigurujete matcher v súlade s dokumentáciou Next.js pre Middleware.

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

Krok 5: Nasadiť a otestovať!

Hotovo! Vaša React aplikácia sa teraz bude automaticky prekladať, keď pridáte akékoľvek reťazce do komponentu Translate. Všimnite si, že len prostredia s povoleniami read/write na API kľúči budú schopné vytvárať nové reťazce určené na preklad. Odporúčame mať uzavreté a zabezpečené stagingové prostredie, v ktorom môžete testovať produkčnú aplikáciu s takýmto API kľúčom a pridávať nové reťazce pred nasadením. Týmto zabránite tomu, aby niekto ukradol váš tajný API kľúč a prípadne nafúknul váš prekladový projekt pridaní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!