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

Ako sa svet stáva viac globalizovaným, pre webových vývojárov je čoraz dôležitejšie vytvárať 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 návode si ukážeme, ako pridať internacionalizáciu do vašej React Next.js aplikácie so serverovým renderovaním. TL;DR: Pozrite si tu celý príklad.

Tento návod je určený pre aplikácie Next.js, ktoré používajú Pages Router.
Ak používate App Router, pozrite si radšej 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 i18n knižnicu. Existuje niekoľko populárnych knižníc, vrátane next-intl. Avšak v tomto príklade použijeme TacoTranslate.

TacoTranslate automaticky prekladá vaše reťazce do akéhokoľvek jazyka pomocou špičkovej umelej inteligencie a zbavuje vás 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 priradené API kľúče. Vytvorte si účet tu. Je to zadarmo a nevyžaduje to pridanie kreditnej karty.

V používateľskom rozhraní aplikácie TacoTranslate vytvorte projekt a prejdite na kartu API kľúče. 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ého prostredia na strane klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Predvolený kód náhradnej lokality. 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šeho webu. Viac informácií o origins nájdete 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 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Automaticky nastavíme TACOTRANSLATE_API_KEY čoskoro.

Vytvorenie klienta v samostatnom súbore uľahčuje jeho opätovné použitie neskôr. Teraz, pomocou vlastného /pages/_app.tsx, pridáme poskytovateľa TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Ak už máte vlastné pageProps a _app.tsx, prosím rozšírte definíciu o vlastnosti a kód z vyššie uvedeného.

Krok 4: Implementácia renderovania na strane servera

TacoTranslate umožňuje serverové vykresľovanie vašich prekladov. To výrazne zlepšuje používateľskú skúsenosť tým, že okamžite zobrazí preložený obsah, namiesto najprv záblesku nepreloženého obsahu. Okrem toho môžeme vynechať sieťové požiadavky na klientskej strane, pretože už máme všetky potrebné preklady.

Začneme vytvorením alebo úpravou /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Upravte kontrolu isProduction tak, aby vyhovovala vášmu nastaveniu. Ak je true, TacoTranslate zobrazí verejný API kľúč. Ak sme v lokálnom, testovacom alebo staging prostredí (isProduction is false), použijeme tajný read/write API kľúč, aby sa zabezpečilo odoslanie nových reťazcov na preklad.

Doteraz sme nastavili Next.js aplikáciu iba so zoznamom podporovaných jazykov. Ďalším krokom bude získanie prekladov pre všetky vaše stránky. Na to použijete buď getTacoTranslateStaticProps alebo getTacoTranslateServerSideProps, v závislosti od vašich požiadaviek.

Tieto funkcie prijímajú tri argumenty: jeden objekt typu Next.js Static Props Context, konfiguráciu pre TacoTranslate a nepovinné vlastnosti Next.js. Všimnite si, že hodnota revalidate na getTacoTranslateStaticProps je predvolene nastavená na 60, aby vaše preklady zostali aktuálne.

Ak chcete použiť ktorúkoľvek z týchto funkcií na stránke, predpokladajme, že máte súbor stránky ako /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Teraz by ste už mali byť schopní použiť komponent Translate na preklad reťazcov vo všetkých vašich React komponentoch.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Krok 5: Nasadiť a otestovať!

Sme hotoví! Vaša React aplikácia bude teraz automaticky preložená vždy, keď pridáte ľubovoľné reťazce do komponentu Translate. Všimnite si, že iba 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é staging prostredie, kde môžete testovať vašu produkčnú aplikáciu s takýmto API kľúčom a pridávať nové reťazce predtým, než pôjdete do živého režimu. Týmto predídete tomu, aby niekto ukradol váš tajný API kľúč a potenciálne nafúkol váš prekladový projekt pridávaní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 App Router! Ak narazíte na nejaké 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 akéhokoľvek jazyka a z neho. Začnite ešte dnes!