Nejlepší řešení pro internacionalizaci (i18n) v aplikacích Next.js

Jak to funguje

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é mohou 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: Podívejte se zde na celý příklad.

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

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 jakéhokoli jazyka pomocí nejmodernější AI a zbavuje vás tak nudné správy JSON souborů.

Nainstalujme si 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 účet TacoTranslate, překladatelský projekt a příslušné API klíče. Zde si založte účet. Je to zdarma a nevyžaduje zadání kreditní karty.

V uživatelském rozhraní aplikace TacoTranslate vytvořte projekt a přejděte na záložku jeho 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íč v klientských produkčních prostředích.

Také přidáme další dvě 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“, kde budou uloženy vaše řetězce, například URL vašeho webu. Přečtěte si zde více o origins.

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íčů zmíněných výše. 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í, s použitím 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 prosím definici o vlastnosti a kód uvedené výše.

Krok 4: Implementace serverového renderování

TacoTranslate umožňuje vykreslování překladů na straně serveru. To výrazně zlepšuje uživatelský zážitek, protože se ihned zobrazí přeložený obsah, namísto nejprve záblesku nepřeloženého obsahu. Navíc můžeme na klientovi vynechat 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 podle vašeho 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ý read/write API klíč, aby se zajistilo odeslání nových řetězců k překladu.

Dosud 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 požadavků.

Tyto funkce přijímají tři argumenty: objekt typu 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í.

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 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í!

Máme hotovo! Vaše aplikace Next.js 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 na 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 testovat svou produkční aplikaci s takovým API klíčem a přidávat nové řetězce ještě před spuštěním do produkce. Tím zabráníte komukoli 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ů.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!