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é dokážou vyhovět uživatelům z různých zemí a kultur. Jedním z hlavních způsobů, jak toho dosáhnout, je internacionalizace (i18n), která vám umožňuje přizpůsobit 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 s vykreslováním na straně serveru. TL;DR: Podívejte se na celý příklad 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

Abychom ve vaší aplikaci Next.js zavedli internacionalizaci, nejprve vybereme knihovnu pro 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 libovolného jazyka pomocí špičkové AI a ušetří vám práci s nudnou správou JSON souborů.

Nainstalujme jej 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 účet TacoTranslate, překladový projekt a související API klíče. Vytvořte si účet zde. 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 jeho záložku API keys. Vytvořte jeden read klíč a jeden read/write klíč. Uložíme je jako proměnné prostředí. read klíč je to, čemu říká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

Dbejte, aby se tajný API klíč read/write nikdy nedostal do klientské části produkčního prostředí.

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 (fallback) locale. 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. Více informací o originách najdete zde.

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

Krok 3: Nastavení TacoTranslate

Pro integraci TacoTranslate do vaší aplikace je třeba vytvořit klienta, který bude používat dříve získané API klíče. Například vytvořte soubor /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 nadefinujeme TACOTRANSLATE_API_KEY.

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

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, protože se přeložený obsah zobrazí okamžitě místo krátkého zobrazení 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 potřebné překlady.

Začneme vytvořením nebo úpravou /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 se nacházíme v lokálním, testovacím nebo stagingovém prostředí (isProduction is false), použijeme tajný API klíč read/write tak, aby se nové řetězce odesílaly k překladu.

Dosud jsme v Next.js aplikaci pouze nastavili 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: jeden Next.js Static Props Context objekt, 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, takže vaše překlady zůstanou aktuální.

Chcete-li kteroukoliv z těchto funkcí použít na stránce, předpokládejme, že máte soubor stránky, například /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 svých React komponentách.

import {Translate} from 'tacotranslate/react';

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

Krok 5: Nasadit a otestovat!

Hotovo! Vaše Next.js aplikace bude nyní automaticky překládána, když přidáte jakékoliv řetězce do komponenty Translate. Všimněte si, že pouze prostředí, která mají na API klíči oprávnění read/write, budou schopna vytvářet nové řetězce určené 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 nasazením do provozu. Tím zabráníte tomu, aby někdo ukradl váš tajný API klíč, a případně nechtěnému nafouknutí 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!