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

Ako sa svet stáva globalizovanejším, je pre webových vývojárov čoraz dôležitejšie vytvárať 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 si ukážeme, ako pridať internacionalizáciu do vašej React Next.js aplikácie s podporou serverového renderovania. 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 aplikácii Next.js si najprv vyberieme i18n knižnicu. 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, prekladateľský projekt a súvisiace API kľúče. Vytvorte si účet tu. Je to zadarmo a nevyžaduje sa zadanie kreditnej karty.

V užívateľskom rozhraní aplikácie TacoTranslate vytvorte projekt a prejdite na jeho záložku 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ý kľúč API read/write 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ý fallback lokalizačný kód. 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 origins si prečítate tu.

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

Krok 3: Nastavenie TacoTranslate

Aby ste integrovali TacoTranslate do svojej aplikácie, budete potrebovať 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 znamená, ž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>
	);
}

Prvou vecou, ktorú treba poznamenať, je, že používame náš parameter Dynamic Route [locale] na získavanie prekladov pre daný jazyk. Okrem toho generateStaticParams zabezpečuje, že všetky kódy lokalizácie, ktoré máte pre svoj projekt aktivované, sú predrerenderované.

Teraz si postavme 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 serverového renderovania

TacoTranslate podporuje server side rendering. Toto výrazne zlepšuje používateľský zážitok tým, že okamžite zobrazuje preložený obsah, namiesto toho, aby sa najprv objavil záblesk nepreloženého obsahu. Okrem toho môžeme preskočiť sieťové požiadavky na klientskej strane, pretože už máme k dispozícii preklady, ktoré potrebujeme pre stránku, ktorú používateľ prehliada.

Na nastavenie serverového renderovania 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 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, že smerovanie a presmerovanie budú fungovať 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 ste nastavili matcher v súlade s dokumentáciou Next.js Middleware.

Na klientovi môžete upraviť cookie locale, aby ste zmenili preferovaný jazyk používateľa. Pozrite si kompletný príklad kódu pre nápady, 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 Translate komponentu. Všimnite si, že iba prostredia s read/write oprávneniami na API kľúči budú môcť vytvárať nové reťazce na preklad. Odporúčame mať uzavreté a zabezpečené stagingové prostredie, kde môžete otestovať svoju produkčnú aplikáciu s takýmto API kľúčom a pridávať nové reťazce pred spustením do prevádzky. Týmto zabezpečíte, že nikto neukradne váš tajný API kľúč a potenciálne nenafúkne váš prekladateľský projekt pridávaním nových, nesúvisiacich reťazcov.

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

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