Najlepšie riešenie pre internacionalizáciu (i18n) v aplikáciách Next.js

Ako to funguje

Ako sa svet globalizuje, 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átumu.

V tomto návode si ukážeme, ako pridať internacionalizáciu do vašej React Next.js aplikácie s vykresľovaním na serveri. TL;DR: Pozrite si celý príklad tu.

Táto príručka je určená pre aplikácie Next.js, ktoré používajú Pages Router.
Ak používate App Router, pozrite si namiesto toho túto príručku.

Krok 1: Nainštalujte knižnicu i18n

Aby sme do vašej Next.js aplikácie zaviedli 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 budeme používať TacoTranslate.

TacoTranslate automaticky prekladá vaše reťazce do ľubovoľného jazyka pomocou špičkovej umelej inteligencie a oslobodí vás od zdĺhavého spravovania JSON súborov.

Nainštalujme ho pomocou npm v 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 súvisiace API kľúče. Vytvorte si účet tu. Je to zadarmo a nemusíte zadávať kreditnú kartu.

Vo webovom 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 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ľúč v produkčných prostrediach na strane klienta.

Pridáme tiež dve ďalšie 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š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

Ak chcete integrovať TacoTranslate do svojej aplikácie, budete musieť vytvoriť klienta pomocou API kľúčov uvedených vyššie. 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 nastavíme TACOTRANSLATE_API_KEY.

Vytvorenie klienta v samostatnom súbore uľahčuje 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 uvedené vyššie.

Krok 4: Implementácia vykresľovania na strane servera

TacoTranslate umožňuje renderovanie na strane servera vašich prekladov. To výrazne zlepšuje používateľský zážitok, pretože preložený obsah sa zobrazí okamžite a nedochádza k krátkemu zobrazeniu nepreloženého obsahu. Okrem toho môžeme na klientskej strane preskočiť 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 true, TacoTranslate zobrazí verejný API kľúč. Ak sa nachádzame v lokálnom, testovacom alebo staging prostredí (isProduction is false), použijeme tajný API kľúč read/write, aby sme zaistili, že nové reťazce budú odoslané na preklad.

Doteraz sme v aplikácii Next.js nastavili iba zoznam 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 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 na getTacoTranslateStaticProps je predvolene nastavené na 60, aby vaše preklady zostali aktuálne.

Aby ste použili ktorúkoľvek 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 už mali byť schopní používať 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 aplikácia Next.js bude teraz automaticky prekladaná vždy, keď pridáte akékoľvek reťazce do komponentu Translate. Upozorňujeme, že iba prostredia s oprávneniami read/write pre kľúč API budú schopné vytvárať nové reťazce na preklad. Odporúčame mať uzavreté a zabezpečené stagingové prostredie, kde môžete otestovať vašu produkčnú aplikáciu s takýmto API kľúčom a pridať nové reťazce pred nasadením do produkcie. Týmto zabránite komukoľvek ukradnúť váš tajný API kľúč a potenciálne nafúknuť váš prekladový projekt pridávaním nových, nesúvisiacich reťazcov.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!