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 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 vaši aplikaci různým jazykům, měnám a formátům data.

V tomto tutoriálu si ukážeme, jak přidat internacionalizaci do vaší React Next.js aplikace se server-side renderingem. TL;DR: Kompletní příklad najdete 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

Pro implementaci internacionalizace ve vaší Next.js aplikaci nejprve vybereme i18n knihovnu. 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 jakéhokoli jazyka pomocí špičkové AI a ušetří vám tak úmornou správu JSON souborů.

Nainstalujme ho pomocí npm ve vašem terminálu:

npm install tacotranslate

Krok 2: Vytvořte si zdarma účet TacoTranslate

Teď, 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 to zadání platební karty.

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na záložku s API klíči. 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řenovém adresáři vašeho projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Ujistěte se, že nikdy neprozradíte tajný read/write API klíč do produkčního 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 jej nastavíme na en pro angličtinu.
• TACOTRANSLATE_ORIGIN: „Složka“, kde budou uloženy vaše řetězce, 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

Pro integraci TacoTranslate s vaší aplikací budete muset vytvořit klienta pomocí dříve získaných API klíčů. Například vytvořte soubor nazvaný /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;

Klíč TACOTRANSLATE_API_KEY budeme brzy automaticky definovat.

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 již máte vlastní pageProps a _app.tsx, prosím doplňte definici o vlastnosti a kód uvedené výše.

Krok 4: Implementace server-side renderování

TacoTranslate umožňuje serverové vykreslování vašich překladů. To výrazně zlepšuje uživatelskou zkušenost tím, že okamžitě zobrazí přeložený obsah, místo aby se nejprve zobrazil záblesk nepřeloženého obsahu. Navíc můžeme na klientovi přeskočit síťové požadavky, protože již 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 tak, aby vyhovovala vašemu nastavení. Pokud true, TacoTranslate zobrazí veřejný klíč API. Pokud se nacházíme v místním, testovacím nebo přípravném prostředí (isProduction is false), použijeme tajný klíč rozhraní API read/write , abychom zajistili, že budou nové řetězce odeslány k překladu.

Doposud jsme v aplikaci Next.js 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 potřeb.

Tyto funkce přijímají tři argumenty: jeden objekt Next.js Static Props Context, konfiguraci pro TacoTranslate a volitelné vlastnosti Next.js. Vezměte prosím na vědomí, že revalidate u getTacoTranslateStaticProps je ve výchozím nastavení nastaven na 60, takže vaše překlady zůstanou aktuální.

Pro použití kterékoliv funkce 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 pro překlad ř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řekládána, když přidáte jakékoliv řetězce do komponenty Translate. Vezměte na vědomí, že pouze prostředí s oprávněními read/write pro API klíč 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 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ím zabráníte komukoliv ukrást váš tajný API klíč a případně nafouknout váš překladatelský projekt přidáváním nových, nesouvisejících řetězců.

Nezapomeňte zkontrolovat kompletní příklad na našem GitHub profilu. Najdete tam také příklad, jak to udělat pomocí App Routeru! 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 a z více než 75 jazyků. Začněte ještě dnes!