Jak implementovat internacionalizaci v aplikaci Next.js, která používá Pages Router

Jak se svět globalizuje, je pro webové vývojáře čím dál důležitější vytvářet aplikace, které dokážou vyhovět uživatelům z různých zemí a kultur. Jedním z klíčových způsobů, jak toho dosáhnout, je internacionalizace (i18n), která vám umožní přizpůsobit vaši aplikaci různým jazykům, měnám a formátům dat.

V tomto návodu si ukážeme, jak přidat internacionalizaci do vaší React Next.js aplikace s renderováním na straně serveru. TL;DR: Podívejte se na celý příklad zde.

Tento průvodce je určen pro aplikace Next.js, které používají Pages Router.
Pokud používáte App Router, podívejte se prosím místo toho na tento průvodce.

Krok 1: Nainstalujte knihovnu i18n

Abychom implementovali internacionalizaci ve vaší Next.js aplikaci, nejprve vybereme i18n knihovnu. Existuje několik oblíbených knihoven, včetně next-intl. V tomto příkladu však budeme používat TacoTranslate.

TacoTranslate automaticky překládá vaše texty do libovolného jazyka pomocí špičkové umělé inteligence a zbavuje vás únavné správy JSON souborů.

Nainstalujme jej pomocí npm v terminálu:

npm install tacotranslate

Krok 2: Vytvořte si bezplatný účet TacoTranslate

Teď, když máte modul nainstalovaný, je čas vytvořit si účet TacoTranslate, překladový projekt a související API klíče. Vytvořte si účet zde. Je to zdarma a nevyžaduje to zadání platební karty.

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na záložku API klíčů. Vytvořte jeden read klíč a jeden read/write klíč. Uložíme je jako proměnné prostředí. read klíč nazýváme public a read/write klíč je secret. Například je můžete přidat do souboru .env v kořenu vašeho projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ujistěte se, že tajný read/write API klíč nikdy neunikne do produkčního prostředí na straně klienta.

Přidáme také dvě další proměnné prostředí: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód lokality (fallback). V tomto příkladu ho nastavíme na en pro angličtinu.
• TACOTRANSLATE_ORIGIN: „složka“, kde budou vaše řetězce uloženy, například URL vašeho webu. Přečtěte si více o origínech zde.

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

Krok 3: Nastavení TacoTranslate

Chcete-li integrovat TacoTranslate do vaší aplikace, budete muset vytvořit klienta pomocí dříve získaných API klíčů. Například vytvořte soubor pojmenovaný /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;

Brzy automaticky nastavíme TACOTRANSLATE_API_KEY.

Vytvoření klienta v samostatném souboru usnadňuje jeho pozdější opětovné použití. Nyní, při použití vlastního /pages/_app.tsx, přidáme poskytovatele 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>
	);
}

Pokud již máte vlastní pageProps a _app.tsx, rozšiřte prosím definici o výše uvedené vlastnosti a kód.

Krok 4: Implementace vykreslování na straně serveru

TacoTranslate umožňuje vykreslování překladů na straně serveru. To výrazně zlepšuje uživatelský zážitek tím, že se přeložený obsah zobrazí okamžitě, místo aby se nejdříve objevil záblesk nepřeloženého obsahu. Navíc můžeme na klientu vynechat síťové požadavky, protože už máme všechny potřebné překlady.

Začneme vytvořením nebo ú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 podle vašeho nastavení. Pokud je true, TacoTranslate zpřístupní veřejný API klíč. Pokud se nacházíme v lokálním, testovacím nebo stagingovém prostředí (isProduction is false), použijeme tajný API klíč read/write tak, aby se nové řetězce odesílaly k překladu.

Až dosud jsme v Next.js aplikaci nastavili pouze seznam podporovaných jazyků. Dalším krokem bude načtení překladů pro všechny vaše stránky. K tomu použijete buď getTacoTranslateStaticProps nebo getTacoTranslateServerSideProps, podle vašich požadavků.

Tyto funkce přijímají tři argumenty: jeden objekt Next.js Static Props Context, konfiguraci pro TacoTranslate a volitelné vlastnosti Next.js. Všimněte si, že revalidate na getTacoTranslateStaticProps je ve výchozím nastavení nastaveno na 60, aby byly vaše překlady aktuální.

Pro použití kterékoliv z těchto funkcí na stránce předpokládejme, že máte soubor stránky jako /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!"/>;
}

Nyní byste měli být schopni používat komponentu Translate k překladu řetězců ve všech vašich React komponentách.

import {Translate} from 'tacotranslate/react';

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

Krok 5: Nasadit a otestovat!

Jsme hotovi! Vaše React aplikace bude nyní automaticky přeložena, když přidáte jakékoli řetězce do komponenty Translate. Vezměte prosím na vědomí, že pouze prostředí s oprávněními read/write u API klíče budou schopna vytvářet nové řetězce k překladu. Doporučujeme mít uzavřené a zabezpečené stagingové prostředí, kde můžete otestovat svou produkční aplikaci s takovým API klíčem a přidat nové řetězce před spuštěním. Tím zabráníte tomu, aby někdo ukradl váš tajný API klíč a případně nafoukl váš překladový projekt přidáváním nových, nesouvisejících řetězců.

Nezapomeňte se podívat na kompletní příklad na našem GitHub profilu. Tam také najdete příklad, jak to udělat pomocí App Router! Pokud narazíte na nějaké problémy, neváhejte nás kontaktovat, rádi vám pomůžeme.

TacoTranslate vám umožňuje automaticky lokalizovat vaše React aplikace rychle do i z více než 75 jazyků. Začněte ještě dnes!