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 čím dál tím 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 dat.

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 návod 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 návod.

Krok 1: Nainstalujte knihovnu i18n

Pro implementaci internacionalizace ve vaší aplikaci Next.js si nejprve 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 řetězce do libovolného jazyka pomocí špičkové umělé inteligence a zbavuje vás nudné správy JSON souborů.

Nainstalujme jej 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 svůj účet TacoTranslate, překladatelský projekt a související API klíče. Založte si účet zde. Je to zdarma a nevyžaduje to přidání kreditní karty.

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na kartu API klíče. Vytvořte jeden read klíč a jeden read/write klíč. Tyto klíče uložíme 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

Vždy se ujistěte, že nikdy neprozradíte tajný read/write API klíč 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 záložního 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

Pro integraci TacoTranslate s vaší aplikací budete muset vytvořit klienta pomocí API klíčů z dřívějška. 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 budeme automaticky definovat TACOTRANSLATE_API_KEY.

Vytvoření klienta v samostatném souboru usnadňuje jeho opětovné použití později. Nyní, pomocí 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 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ě zobrazuje přeložený obsah, místo prvotního záblesku nepřeloženého obsahu. Navíc se můžeme vyhnout síťovým požadavkům na straně klienta, 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 získání 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. Vezměte na vědomí, že revalidate u getTacoTranslateStaticProps je ve výchozím nastavení nastaven 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 textů ve všech vašich React komponentách.

import {Translate} from 'tacotranslate/react';

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

Krok 5: Nasazení a testování!

Jsme hotovi! 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í s oprávněními read/write k API klíči 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řidávat nové řetězce před spuštěním do živého provozu. To zabrání komukoli ukrást váš tajný API klíč a potenciálně nafouknout váš překladový projekt přidáním nových, nesouvisejících řetězců.

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

TacoTranslate vám umožní automaticky lokalizovat vaše React aplikace rychle do jakéhokoli jazyka a z něj. Začněte ještě dnes!