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 obsloužit uživatele 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 se server-side renderingem. TL;DR: Kompletní příklad najdete 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 na tento průvodce.

Krok 1: Nainstalujte knihovnu i18n

Pro implementaci internacionalizace ve vaší Next.js aplikaci si nejprve vybereme knihovnu pro i18n. Existuje několik populárních knihoven, včetně next-intl. Nicméně v tomto příkladu budeme používat TacoTranslate.

TacoTranslate automaticky překládá vaše řetězce do jakéhokoli jazyka pomocí špičkové AI a zbavuje vás únavné 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 účet TacoTranslate, překladatelský projekt a související API klíče. Vytvořte si účet zde. 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 .env souboru 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é další dvě proměnné prostředí: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí záložní kód locale. 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. Další informace o originálech zde.

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

Krok 3: Nastavení TacoTranslate

Pro integraci TacoTranslate do vaší aplikace 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 automaticky nadefinujeme TACOTRANSLATE_API_KEY.

Vytvoření klienta v samostatném souboru usnadňuje jeho opětovné použití v budoucnu. Nyní přidáme poskytovatele TacoTranslate pomocí vlastního /pages/_app.tsx.

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 vykreslování na straně serveru

TacoTranslate umožňuje vykreslování vašich překladů na 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á chvíle nepřeloženého obsahu. Navíc můžeme přeskočit síťové požadavky 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.

Do této chvíle 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. Všimněte si, že revalidate u getTacoTranslateStaticProps je ve výchozím nastavení nastaven na 60, aby byly vaše překlady 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žívat komponentu Translate k překladu řetězců ve všech vašich React komponentech.

import {Translate} from 'tacotranslate/react';

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

Krok 5: Nasazení a testování!

Jsme hotovi! Vaše aplikace Next.js 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í 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 před spuštěním do produkce. To zabrání komukoliv ukrást váš tajný API klíč a potenciálně rozšiřovat váš překladatelský 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. Tam také najdete příklad, jak to udělat pomocí App Router! Pokud narazíte na jakékoliv problémy, neváhejte nás kontaktovat, rádi vám pomůžeme.

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