Jak implementovat internacionalizaci v aplikaci Next.js, která používá App Router

Jak se svět stává 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 klíčových způsobů, jak toho dosáhnout, je prostřednictvím 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 článku si ukážeme, jak přidat internacionalizaci do vaší React Next.js aplikace se server-side renderingem. TL;DR: Kompletní příklad najdete zde.

Tato příručka je určena pro aplikace Next.js, které používají App Router.
Pokud používáte Pages Router, podívejte se místo toho na 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 použijeme TacoTranslate.

TacoTranslate automaticky překládá vaše řetězce do jakéhokoli jazyka pomocí špičkové AI a zbavuje vás 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 v TacoTranslate, překladatelský projekt a související API klíče. Vytvořte si zde účet. 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 záložku 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íč 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í kód náhradního jazyka. V tomto příkladu jej 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íčů z předchozího kroku. 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Brzy automaticky definujeme TACOTRANSLATE_API_KEY a TACOTRANSLATE_PROJECT_LOCALE.

Vytvoření klienta v samostatném souboru usnadňuje jeho opětovné použití později. getLocales je jen utilitní funkce s vestavěnou obsluhou chyb. Nyní vytvořte soubor s názvem /app/[locale]/tacotranslate.tsx, kde implementujeme poskytovatele TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Všimněte si 'use client';, což označuje, že se jedná o klientskou komponentu.

S připraveným poskytovatelem kontextu nyní vytvořte soubor s názvem /app/[locale]/layout.tsx, což je kořenové rozvržení v naší aplikaci. Všimněte si, že tato cesta obsahuje složku využívající Dynamic Routes, kde [locale] je dynamický parametr.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

První věc, kterou je třeba zde poznamenat, je, že používáme náš Dynamic Route parametr [locale] k načtení překladů pro daný jazyk. Kromě toho generateStaticParams zajišťuje, že všechny locale kódy, které jste pro svůj projekt aktivovali, jsou předrenderovány.

Teď si vytvoříme naši první stránku! Vytvořte soubor pojmenovaný /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Všimněte si proměnné revalidate, která říká Next.js, aby po 60 sekundách stránku znovu sestavil a udržoval vaše překlady aktuální.

Krok 4: Implementace server-side renderingu

TacoTranslate podporuje server-side rendering. To výrazně zlepšuje uživatelský zážitek tím, že okamžitě zobrazí přeložený obsah, místo aby se nejprve zobrazil záblesk nepřeloženého obsahu. Navíc můžeme přeskočit síťové požadavky na straně klienta, protože již máme překlady, které potřebujeme pro stránku, kterou uživatel právě prohlíží.

Chcete-li nastavit server-side rendering, vytvořte nebo upravte /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

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.

Aby směrování a přesměrování fungovalo podle očekávání, budeme muset vytvořit soubor s názvem /middleware.ts. Pomocí Middleware můžeme uživatele přesměrovat na stránky zobrazené v jejich preferovaném jazyce.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Nezapomeňte nastavit matcher v souladu s dokumentací Next.js Middleware.

Na klientovi můžete upravit locale cookie, abyste změnili preferovaný jazyk uživatele. Pro nápady, jak to udělat, si prosím prohlédněte kompletní ukázkový kód!

Krok 5: Nasazení a testování!

Máme hotovo! Vaše React 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í 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 nasazením do ostrého provozu. Tím zabráníte komukoliv ukrást váš tajný API klíč a potenciálně nafouknout váš překladatelský projekt přidáním nových, nesouvisejících řetězců.

Nezapomeňte prohlédnout si kompletní příklad na našem GitHub profilu. Tam také najdete příklad, jak to udělat s použitím Pages Router ! Pokud narazíte na jakékoliv problémy, neváhejte napsat nám, rádi vám pomůžeme.

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