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

Ako sa svet stáva viac globalizovaným, je pre webových vývojárov čoraz dôležitejšie vytvárať 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 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átumov.

V tomto návode preskúmame, 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 sprievodca je určený pre Next.js aplikácie, ktoré používajú Pages Router.
Ak používate App Router, pozrite si namiesto toho tento návod.

Krok 1: Nainštalujte knižnicu i18n

Aby sme vo vašej Next.js aplikácii implementovali internacionalizáciu, najprv si 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 ľ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 v 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, prekladový projekt a príslušné API kľúče. Vytvorte si účet tu. Je to zadarmo a nevyžaduje zadanie 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 nazývame 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

Dávajte si pozor, aby ste nikdy neprezradili tajný read/write API kľúč v produkčných prostrediach na klientskej strane.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Predvolený kód náhradného jazyka. 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. Viac informácií o origins nájdete 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 vyššie uvedených 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Čoskoro automaticky definujeme TACOTRANSLATE_API_KEY.

Vytvorenie klienta v samostatnom súbore uľahčí jeho opätovné použitie neskôr. Teraz, pri použití 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 vykresľovanie vašich prekladov na strane servera. To výrazne zlepšuje používateľský zážitok, pretože preložený obsah sa zobrazí okamžite, namiesto krátkeho záblesku nepreloženého obsahu. Okrem toho môžeme na klientskej strane vynechať sieťové požiadavky, 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 nové reťazce odoslali na preklad.

Doteraz sme v Next.js aplikácii nakonfigurovali iba zoznam podporovaných jazykov. Ďalším krokom bude načítanie prekladov pre všetky vaše stránky. Na to použijete buď getTacoTranslateStaticProps alebo getTacoTranslateServerSideProps podľa vašich požiadaviek.

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

Ak chcete použiť jednu z týchto funkcií na stránke, predpokladajme, že máte súbor stránky, napríklad /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 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ť!

Hotovo! Vaša React aplikácia sa bude teraz automaticky prekladať, keď do komponentu Translate pridáte ľubovoľné reťazce. Všimnite si, že len prostredia s povoleniami read/write na API kľúči budú môcť vytvárať nové reťazce určené na preklad. Odporúčame mať uzavreté a zabezpečené staging (testovacie) prostredie, kde môžete otestovať svoju produkčnú aplikáciu s takýmto API kľúčom a pridávať nové reťazce pred nasadením do prevádzky. Tým zabránite komukoľvek komukoľvek kradnúť váš tajný API kľúč a potenciálne nafukovať váš prekladový projekt pridávaním nových, nesúvisiacich reťazcov.

Nezabudnite si pozrieť kompletný príklad na našom GitHub profile. Tam tiež nájdete 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žní rýchlo a automaticky lokalizovať vaše React aplikácie do a z viac ako 75 jazykov. Začnite ešte dnes!