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

S tým, ako sa svet globalizuje, je čoraz dôležitejšie, aby weboví vývojári vytvárali aplikácie, ktoré dokážu vyhovieť používateľom 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ť vašu aplikáciu rôznym jazykom, menám a formátom dátumov.

V tomto článku preskúmame, ako pridať internacionalizáciu do vašej aplikácie React Next.js s podporou server-side renderingu. TL;DR: Kompletný príklad nájdete 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 aplikácii Next.js si najskôr 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 najmodernejšej AI a oslobodzuje vás od zdĺhavého spravovania JSON súborov.

Nainštalujme si ho pomocou npm vo vašom 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 sa pridanie kreditnej karty.

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

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

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

• TACOTRANSLATE_DEFAULT_LOCALE: Predvolený záložný kód lokalizácie. 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 adresa vašej webovej stránky. Viac o pôvodoch sa dozviete tu.

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

Krok 3: Nastavenie TacoTranslate

Na integráciu TacoTranslate s vašou aplikáciou budete musieť vytvoriť klienta pomocou API kľúčov z predchádzajúceho kroku. 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čuje jeho opätovné použitie neskôr. getLocales je len pomocná funkcia s niektorými zabudovanými mechanizmami na spracovanie 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 indikuje, že ide o klientsku komponentu.

Keď je poskytovateľ kontextu pripravený na použitie, vytvorte súbor s názvom /app/[locale]/layout.tsx, koreňové rozloženie v našej aplikácii. Všimnite si, že táto cesta má 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ým, čo treba poznamenať, je to, že používame náš Dynamic Route parameter [locale] na načítanie prekladov pre daný jazyk. Okrem toho, generateStaticParams zabezpečuje predvygenerovanie všetkých jazykových kódov, ktoré máte pre svoj projekt aktivované.

Teraz si vytvorme 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á hovorí Next.js, aby stránku po 60 sekundách znova zostavil a udržiaval vaše preklady aktuálne.

Krok 4: Implementácia server-side renderingu

TacoTranslate podporuje server-side rendering. To výrazne zlepšuje používateľský zážitok tým, že ihneď zobrazí preložený obsah, namiesto toho, aby sa najprv zobrazil záblesk nepreloženého obsahu. Okrem toho môžeme vynechať sieťové požiadavky na klientovi, pretože už máme preklady, ktoré potrebujeme pre stránku, ktorú používateľ práve prezerá.

Na nastavenie server side renderingu vytvorte alebo upravte súbor /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 true, TacoTranslate zobrazí verejný kľúč API. Ak sa nachádzame v lokálnom, testovacom alebo prípravnom prostredí (isProduction is false), použijeme tajný kľúč rozhrania API read/write , aby sme sa uistili, že nové reťazce sa odosielajú na preklad.

Aby sme zabezpečili správnu funkciu smerovania a presmerovania, budeme musieť vytvoriť súbor nazvaný /middleware.ts. Použitím Middleware môžeme presmerovať používateľov na stránky prezentované 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 máte nastavený matcher v súlade s dokumentáciou Next.js Middleware.

Na klientskej strane môžete upraviť cookie locale, aby ste zmenili preferovaný jazyk používateľa. Pozrite si kompletný príklad kódu pre inšpiráciu, ako to urobiť!

Krok 5: Nasadiť a otestovať!

Sme hotoví! Vaša React aplikácia bude teraz automaticky preložená, keď pridáte akékoľvek reťazce do komponentu Translate. Upozorňujeme, že len prostredia s oprávneniami read/write na API kľúč budú môcť vytvárať nové reťazce na preklad. Odporúčame mať uzavreté a zabezpečené testovacie prostredie, kde môžete testovať svoju produkčnú aplikáciu s takýmto API kľúčom a pridávať nové reťazce pred jej zverejnením. Týmto zabráni niekto ukradnúť váš tajný API kľúč a potenciálne nafúknuť váš prekladový projekt pridávaním nových, nesúvisiacich reťazcov.

Nezabudnite si pozrieť kompletný príklad na našom profile GitHub. Tam nájdete aj príklad, ako to spraviť pomocou Pages Router ! Ak narazíte na nejaké problémy, neváhajte nás kontaktovať, radi vám pomôžeme.

TacoTranslate vám umožňuje rýchlo a automaticky lokalizovať vaše React aplikácie do a z akéhokoľvek jazyka. Začnite ešte dnes!