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

Jak to funguje

Jak se svět stále více globalizuje, 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 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: 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 podívejte se 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 budeme používat TacoTranslate.

TacoTranslate automaticky překládá vaše řetězce do jakéhokoliv jazyka za použití špičkové AI a uvolňuje vás od 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 účet TacoTranslate, překladatelský projekt a příslušné 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 s API klíči. 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.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Výchozí kód náhradního locale. 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 více o origínech zde.

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

Krok 3: Nastavení TacoTranslate

Chcete-li integrovat TacoTranslate s vaší aplikací, budete muset vytvořit klienta pomocí klíčů API z dřívějška. Vytvořte například 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í přidáme poskytovatele TacoTranslate pomocí vlastního souboru /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 už máte vlastní pageProps a _app.tsx, prosím rozšiřte definici o vlastnosti a kód z výše uvedeného.

Krok 4: Implementace serverového vykreslování

TacoTranslate umožňuje serverové vykreslování vašich překladů. To výrazně zlepšuje uživatelský zážitek tím, že okamžitě zobrazuje přeložený obsah, místo prvotního záblesku nepřeloženého obsahu. Navíc můžeme přeskočit síťové požadavky na klientovi, 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'),
	});
};

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.

Doposud 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 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 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 komponentách.

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. Vezměte prosím na vědomí, že pouze prostředí s oprávněními read/write k API klíči 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 otestovat 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. Toto zamezí komukoliv ukrást váš tajný API klíč a potenciálně nenápadně nafouknout 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 profilu GitHub. Najdete tam také příklad, jak to udělat pomocí App Routeru! Pokud narazíte na nějaké 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 i z jakéhokoli jazyka. Začněte ještě dnes!