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

Ako sa svet stáva viac globalizovaným, je čoraz dôležitejšie, aby weboví vývojári vytvárali aplikácie, ktoré môžu vyhovieť používateľom 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 so serverovým renderovaním. TL;DR: Tu si pozrite 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

Na implementáciu internacionalizácie vo vašej aplikácii Next.js najskôr vyberieme knižnicu i18n. Existuje niekoľko populárnych knižníc, vrátane next-intl. V tomto príklade však použijeme TacoTranslate.

TacoTranslate automaticky prekladá vaše reťazce do akéhokoľvek jazyka pomocou špičkovej umelej inteligencie 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

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

V užívateľskom rozhraní aplikácie 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ľúč 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 na produkčných prostrediach na strane klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Predvolený jazykový kód ako záloha. 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. Prečítajte si viac o pôvodoch tu.

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

Krok 3: Nastavenie TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 nastavíme TACOTRANSLATE_API_KEY a TACOTRANSLATE_PROJECT_LOCALE.

Vytvorenie klienta v samostatnom súbore umožňuje jeho jednoduché opätovné použitie neskôr. getLocales je len užitočná funkcia s niekoľký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 naznačuje, že ide o klientskú súčiastku.

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á vec, 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 lokálne kódy, ktoré ste aktivovali pre váš projekt, sú predvygenerované.

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 znovu zostavil stránku po 60 sekundách a udržiaval vaše preklady aktuálne.

Krok 4: Implementácia serverového renderovania

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

Ak chcete nastaviť server-side rendering, 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 bude fungovať podľa očakávaní, budeme musieť vytvoriť súbor s názvom /middleware.ts. Použitím 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 matcher nastavili v súlade s dokumentáciou Next.js Middleware.

Na klientovi môžete zmeniť cookie locale na úpravu preferovaného jazyka používateľa. Pre nápady, ako to urobiť, si prosím pozrite kompletný príkladový kód!

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 povoleniami read/write na API kľúči budú schopné vytvárať nové reťazce na preklad. Odporúčame mať uzavreté a zabezpečené staging prostredie, kde môžete testovať vašu produkčnú aplikáciu s takým API kľúčom a pridávať nové reťazce pred spustením do živého prostredia. Toto zabráni komukoľvek ukradnúť váš tajný API kľúč a potenciálne nafúknuť váš prekladový projekt pridaním nových, nesúvisiacich reťazcov.

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

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