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

Jak se svět stává stále více globalizovaným, 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žňuje přizpůsobit 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 vykreslováním na straně serveru. TL;DR: Podívejte se na kompletní 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 ve vaší Next.js aplikaci implementovali internacionalizaci, nejprve zvolíme knihovnu i18n. Existuje několik populárních knihoven, včetně next-intl. V tomto příkladu však použijeme TacoTranslate.

TacoTranslate automaticky překládá vaše řetězce do libovolného jazyka pomocí nejmodernější 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

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

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na jeho kartu 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, abyste nikdy nezveřejnili tajný read/write API klíč v produkčním prostředí na straně klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód náhradního jazyka. V tomto příkladu ho nastavíme na en pro angličtinu.
• TACOTRANSLATE_ORIGIN: „Složka“, kam budou uloženy vaše řetězce, například URL vašeho webu. Další informace o origins najdete zde.

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

Krok 3: Nastavení TacoTranslate

Chcete-li integrovat TacoTranslate s vaší aplikací, budete potřebovat 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 usnadní jeho 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 už máte vlastní pageProps a _app.tsx, prosím rozšiřte definici o výše uvedené vlastnosti a kód.

Krok 4: Implementace vykreslová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 zobrazí přeložený obsah okamžitě, místo aby se nejdříve 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 souboru /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, aby vyhovovala vašemu nastavení. Pokud je true, TacoTranslate zpřístupní veřejný klíč API. Pokud se nacházíme v lokálním, testovacím nebo stagingovém prostředí (isProduction is false), použijeme tajný klíč API read/write, abychom zajistili, že nové řetězce budou odeslány k překladu.

Dosud jsme Next.js aplikaci nastavili pouze s výčtem 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 u getTacoTranslateStaticProps je ve výchozím nastavení nastaveno na 60, takže vaše překlady zůstanou aktuální.

Pro použití kterékoliv z 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, kdykoli přidáte libovolné řetězce do komponenty Translate. Vezměte na vědomí, že pouze prostředí s oprávněními read/write na API klíči budou moci vytvářet nové řetězce určené k překladu. Doporučujeme mít uzavřené a zabezpečené stagingové prostředí, kde můžete testovat svou produkční aplikaci s takovým API klíčem a přidávat nové řetězce před nasazením do živého provozu. Tímto zabráníte komukoli komukoli ukrást váš tajný API klíč a případnému nafouknutí vašeho překladového projektu přidáváním nových, nesouvisejících řetězců.

Nezapomeňte se podívat na 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 nějaké problémy, neváhejte nás kontaktovat, rádi vám pomůžeme.

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