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

Ako sa svet stáva čoraz viac globalizovaným, pre webových vývojárov je č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 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 si ukážeme, ako pridať internacionalizáciu do vašej React Next.js aplikácie so server-side renderingom. TL;DR: Kompletný príklad nájdete tu.

Tento návod je určený pre aplikácie Next.js, ktoré používajú Pages Router.
Ak používate App Router, prečítajte 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 i18n knižnicu. 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 AI a odbremení vás od zdĺhavého manažmentu JSON súborov.

Nainštalujme ho cez npm vo vašom termináli:

npm install tacotranslate

Krok 2: Vytvorte si bezplatný účet TacoTranslate

Keďže máte modul nainštalovaný, je čas vytvoriť si účet v TacoTranslate, prekladateľský projekt a súvisiace API kľúče. Vytvorte si účet tu. Je to zadarmo a nevyžaduje pridanie kreditnej karty.

V použí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ý 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 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 adresa vášho webu. Prečítajte si viac o origins tu.

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

Krok 3: Nastavenie TacoTranslate

Aby ste integrovali TacoTranslate do vašej aplikácie, budete si 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Kľúč TACOTRANSLATE_API_KEY bude čoskoro automaticky definovaný.

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, rozšírte definíciu o vlastnosti a kód uvedené vyššie.

Krok 4: Implementácia server-side renderovania

TacoTranslate umožňuje serverové renderovanie vašich prekladov. Toto výrazne zlepšuje používateľský zážitok tým, že okamžite zobrazuje preložený obsah, namiesto najprv záblesku nepreloženého obsahu. Okrem toho môžeme preskočiť sieťové požiadavky na strane klienta, pretože už máme všetky potrebné preklady.

Začneme vytvorením alebo úpravou súboru /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 aplikáciu Next.js iba so zoznamom podporovaných jazykov. Ďalšou vecou, ktorú urobíme, je 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 pri getTacoTranslateStaticProps je predvolene nastavený na 60, aby vaše preklady zostávali 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žívať komponent Translate na preklad reťazcov v rámci všetkých vašich React komponentov.

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á, keď pridáte akékoľvek reťazce do komponentu Translate. Upozorňujeme, že iba 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ýmto API kľúčom a pridávať nové reťazce pred nasadením do ostrého prevádzky. Týmto sa zabráni tomu, aby niekto ukradol váš tajný API kľúč a potenciálne tým nafúkol váš prekladateľský 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 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 viac ako 75 jazykov a zoznamovať sa s nimi. Začnite ešte dnes!