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

S tím, jak se svět globalizuje, je pro webové vývojáře čím dál důležitější vytvářet aplikace, které umějí oslovit uživatele 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žňuje přizpůsobit vaši aplikaci různým jazykům, měnám a formátům dat.

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

Tento průvodce je určen pro Next.js aplikace, 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

Abyste v aplikaci Next.js implementovali internacionalizaci, nejprve si vybereme knihovnu pro i18n. 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 řetězce do libovolného jazyka za pomoci špičkové umělé inteligence a zbavuje vás únavné správy JSON souborů.

Nainstalujme ji pomocí npm v terminálu:

npm install tacotranslate

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

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

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na kartu API keys. Vytvořte jeden read klíč a jeden read/write klíč. Uložíme je jako proměnné prostředí. read klíč je to, čemu říkáme public, a read/write klíč je secret. Například je můžete přidat do souboru .env v kořenovém adresáři vašeho projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Dbejte na to, abyste nikdy neprozradili tajný read/write API klíč v produkčních prostředích na straně klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód náhradního (fallback) jazyka. 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 origins zde.

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

Krok 3: Nastavení TacoTranslate

Chcete-li TacoTranslate integrovat do své aplikace, budete muset vytvořit klienta pomocí výše uvedených API klíčů. Například vytvořte soubor s názvem /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 definujeme TACOTRANSLATE_API_KEY.

Vytvoření klienta v samostatném souboru usnadňuje jeho opětovné použití později. 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 už máte vlastní pageProps a _app.tsx, rozšiřte definici o vlastnosti a kód uvedené výše.

Krok 4: Implementace renderová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 okamžitě zobrazí přeložený obsah, místo aby se nejprve objevil záblesk nepřeloženého obsahu. Navíc můžeme na klientovi 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 bude true, TacoTranslate zobrazí veřejný API klíč. Pokud jsme v lokálním, testovacím nebo staging prostředí (isProduction is false), použijeme tajný read/write API klíč, abychom zajistili, že nové řetězce budou odeslány k překladu.

Dosud jsme v Next.js aplikaci nastavili pouze seznam podporovaných jazyků. Dalším krokem bude získat překlady 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í.

Chcete-li kteroukoliv z těchto funkcí použít na stránce, předpokládejme, že máte soubor stránky, napří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!"/>;
}

Měli byste nyní být schopni použít 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!

Hotovo! Vaše React aplikace bude nyní automaticky překládána, když přidáte jakékoli řetězce do komponenty Translate. Všimněte si, že pouze prostředí disponující oprávněním read/write u API klíče budou moci 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řidávat nové řetězce před jejím nasazením do provozu. Tím zabráníte komukoli ukrást váš tajný API klíč a případnému nafouknutí projektu přidáváním nových, nesouvisejících řetězců.

Nezapomeňte si prohlédnout kompletní příklad na našem profilu na GitHubu. Tam také najdete příklad, jak to udělat pomocí App Router! Pokud narazíte na jakékoli problémy, neváhejte napsat nám, rádi vám pomůžeme.

TacoTranslate umožňuje automatickou lokalizaci vašich React aplikací rychle do a z více než 75 jazyků. Začněte ještě dnes!