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

Jak se svět stává stále globalizovanějším, je pro vývojáře webu 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žní přizpůsobit vaši aplikaci různým jazykům, měnám a formátům data.

V tomto tutoriálu prozkoumáme, jak přidat internacionalizaci do vaší React Next.js aplikace s podporou server-side renderingu. TL;DR: Kompletní příklad naleznete zde.

Tato příručka je určena pro aplikace Next.js, které používají Pages Router.
Pokud používáte App Router, podívejte se prosím místo toho na tuto příručku.

Krok 1: Nainstalujte knihovnu i18n

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

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

npm install tacotranslate

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

Nyní, když máte modul nainstalovaný, je čas vytvořit si svůj účet TacoTranslate, překladatelský projekt a související API klíče. Založte si zde účet. 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 kartu API klíčů. 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.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód výchozí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ší webové stránky. Více informací 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 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í, za 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, rozšiřte definici o vlastnosti a kód z výše uvedeného.

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 okamžitě zobrazí přeložený obsah, místo aby se nejprve objevila krátká záblesková nepřeloženého obsahu. Navíc můžeme na klientovi přeskočit síťové požadavky, protože už máme všechny překlady, které potřebujeme.

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.

Dosud jsme v aplikaci Next.js 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, v závislosti na vašich požadavcích.

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 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: Nasazení a testování!

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 prosím 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é staging prostředí, kde můžete testovat vaši produkční aplikaci s takovým API klíčem a přidávat nové řetězce před samotným nasazením. Tím zabráníte, aby někdo ukradl váš tajný API klíč a případně rozšiřoval váš překladový projekt přidáváním nových, nesouvisejících řetězců.

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

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