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

Jak se svět stále více globalizuje, je pro webové vývojáře stále důležitější vytvářet aplikace, které dokážou obsloužit 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 prozkoumáme, 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 aplikace Next.js, které používají Pages Router.
Pokud používáte App Router, podívejte se místo toho na tento průvodce.

Krok 1: Nainstalujte knihovnu i18n

Abychom do vaší aplikace Next.js zavedli internacionalizaci, nejprve si vybereme knihovnu i18n. Existuje několik populární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 osvobozuje vás od nudné správy JSON souborů.

Nainstalujme jej pomocí npm v terminálu:

npm install tacotranslate

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

Nyní, když máte modul nainstalovaný, je čas vytvořit si účet na 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íč 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, aby se tajný read/write API klíč nikdy nedostal do produkčního prostředí na straně klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód záložního jazyka. V tomto příkladu jej nastavíme na en pro angličtinu.
• TACOTRANSLATE_ORIGIN: “složka”, kde budou vaše řetězce uloženy, například URL vaší webové stránky. Více informací o originách najdete zde.

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

Krok 3: Nastavení TacoTranslate

Aby bylo možné integrovat TacoTranslate do vaší aplikace, budete muset vytvořit klienta pomocí dříve získaný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 nastavíme TACOTRANSLATE_API_KEY.

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

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

TacoTranslate umožňuje vykreslování vašich překladů na straně serveru. To výrazně zlepšuje uživatelský zážitek tím, že přeložený obsah zobrazí okamžitě, místo aby se nejprve objevil záblesk nepřeloženého obsahu. Navíc můžeme na straně klienta přeskočit 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 tak, aby vyhovovala vašemu nastavení. Pokud je 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ý API klíč read/write, aby se zajistilo, že nové řetězce budou odeslány k překladu.

Dosud jsme nastavili Next.js aplikaci pouze s seznamem podporovaných jazyků. Dalším krokem bude načíst 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 u getTacoTranslateStaticProps je ve výchozím nastavení nastaveno na 60, aby vaše překlady zůstaly aktuální.

Chcete-li použít kteroukoliv 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ží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. Poznámka: pouze prostředí s oprávněním 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 produkční aplikaci s takovým API klíčem a přidávat nové řetězce před nasazením do provozu. Tím zabráníte komukoli ukrást váš tajný API klíč a zároveň předejdete tomu, že se váš překladový projekt nafoukne přidáváním nových, nesouvisejících řetězců.

Nezapomeňte si prohlédnout kompletní příklad na našem GitHub profilu. Tam také najdete příklad, jak to udělat pomocí App Router! Pokud narazíte na jakékoliv problémy, neváhejte napište nám, 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!