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

Jak to funguje

Jak se svět 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 s vykreslováním na straně serveru. TL;DR: Podívejte se na celý příklad zde.

Tento průvodce je určen pro Next.js aplikace, 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 zavedení internacionalizace ve vaší Next.js aplikaci si 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 řetězce do libovolného jazyka pomocí špičkové AI a zbavuje vás únavné správy JSON souborů.

Nainstalujme jej v terminálu pomocí npm:

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 související API klíče. Vytvořte si účet zde. Je to zdarma a nevyžaduje, abyste zadali platební kartu.

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í. Klíč read nazýváme public a klíč read/write 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 tajný read/write API klíč se nikdy nedostane do produkčního prostředí na straně klienta.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód záložní lokality. V tomto příkladu jej nastavíme na en pro angličtinu.
• TACOTRANSLATE_ORIGIN: „složka“, kde budou vaše řetězce uloženy, například URL vaší webové stránky. Přečtěte si více o originách zde.

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

Krok 3: Nastavení TacoTranslate

Chcete-li integrovat TacoTranslate do vaší aplikace, budete muset 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 usnadňuje jeho pozdější 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í překladů na straně serveru. To výrazně zlepšuje uživatelský zážitek, protože přeložený obsah se zobrazí okamžitě, místo aby se nejprve objevil záblesk nepřeloženého obsahu. Navíc se můžeme vyhnout síťovým požadavkům na straně klienta, 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'),
	});
};

Přizpůsobte kontrolu isProduction svému nastavení. Pokud je true, TacoTranslate zobrazí veřejný API klíč. Pokud jsme v lokálním, testovacím nebo stagingovém prostředí (isProduction is false), použijeme tajný API klíč read/write abychom zajistili, že nové řetězce budou odeslány k překladu.

Až dosud jsme v Next.js aplikaci 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. Všimněte si, že revalidate u getTacoTranslateStaticProps je ve výchozím nastavení nastaveno na 60, aby vaše překlady zůstávaly aktuální.

Chcete-li použít kteroukoliv 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ží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 aplikace Next.js bude nyní automaticky přeložena, jakmile do komponenty Translate přidáte jakékoli řetězce. Všimněte si, že pouze prostředí, která mají u API klíče oprávnění read/write, 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 uvedením do provozu. Tím zabráníte, aby někdo ukradl váš tajný API klíč, a zároveň zamezíte zbytečnému nafukování vašeho překladového projektu 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!