Jak zaimplementować internacjonalizację w aplikacji Next.js korzystającej z App Router

W miarę jak świat staje się coraz bardziej zglobalizowany, coraz ważniejsze staje się, aby deweloperzy webowi tworzyli aplikacje dostosowane do użytkowników z różnych krajów i kultur. Jednym z kluczowych sposobów osiągnięcia tego jest internacjonalizacja (i18n), która pozwala dostosować aplikację do różnych języków, walut i formatów dat.

W tym artykule omówimy, jak dodać internacjonalizację do aplikacji React Next.js z renderowaniem po stronie serwera. TL;DR: Zobacz pełny przykład tutaj.

Ten przewodnik dotyczy aplikacji Next.js korzystających z App Router.
Jeśli używasz Pages Router, zobacz zamiast tego ten przewodnik.

Krok 1: Zainstaluj bibliotekę i18n

Aby wdrożyć internacjonalizację w swojej aplikacji Next.js, najpierw wybierzemy bibliotekę i18n. Istnieje kilka popularnych bibliotek, w tym next-intl. W tym przykładzie jednak będziemy korzystać z TacoTranslate.

TacoTranslate automatycznie tłumaczy twoje ciągi tekstowe na dowolny język, wykorzystując nowoczesną sztuczną inteligencję, i uwalnia cię od żmudnego zarządzania plikami JSON.

Zainstalujmy je przy użyciu npm w terminalu:

npm install tacotranslate

Krok 2: Utwórz bezpłatne konto TacoTranslate

Teraz, gdy masz moduł zainstalowany, czas utworzyć konto TacoTranslate, projekt tłumaczeniowy i powiązane klucze API. Załóż konto tutaj. To bezpłatne i nie wymaga podawania danych karty kredytowej.

W interfejsie aplikacji TacoTranslate utwórz projekt i przejdź do zakładki z kluczami API. Utwórz jeden read klucz i jeden read/write klucz. Zapiszemy je jako zmienne środowiskowe. Klucz read to to, co nazywamy public, a klucz read/write to secret. Na przykład możesz dodać je do pliku .env w katalogu głównym projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Upewnij się, że nigdy nie ujawnisz tajnego klucza API read/write w środowiskach produkcyjnych po stronie klienta.

Dodamy także dwie dodatkowe zmienne środowiskowe: TACOTRANSLATE_DEFAULT_LOCALE i TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Domyślny kod lokalizacji zapasowej. W tym przykładzie ustawimy go na en dla języka angielskiego.
• TACOTRANSLATE_ORIGIN: “folder”, w którym będą przechowywane twoje teksty, na przykład adres URL twojej strony. Dowiedz się więcej o originach tutaj.

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

Krok 3: Konfiguracja TacoTranslate

Aby zintegrować TacoTranslate z aplikacją, musisz utworzyć klienta, używając wspomnianych wcześniej kluczy API. Na przykład utwórz plik o nazwie /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;

Wkrótce automatycznie zdefiniujemy TACOTRANSLATE_API_KEY i TACOTRANSLATE_PROJECT_LOCALE.

Utworzenie klienta w oddzielnym pliku ułatwia jego ponowne użycie. getLocales to tylko funkcja pomocnicza z wbudowaną obsługą błędów. Teraz utwórz plik o nazwie /app/[locale]/tacotranslate.tsx, w którym zaimplementujemy dostawcę 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>
	);
}

Zwróć uwagę na 'use client'; — oznacza to, że jest to komponent po stronie klienta.

Teraz, gdy provider kontekstu jest gotowy, utwórz plik o nazwie /app/[locale]/layout.tsx, będący głównym layoutem w naszej aplikacji. Zauważ, że ta ścieżka ma folder wykorzystujący Dynamic Routes, gdzie [locale] jest parametrem dynamicznym.

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>
	);
}

Pierwszą rzeczą, którą należy tutaj zauważyć, jest to, że używamy naszego parametru Dynamic Route [locale] do pobierania tłumaczeń dla tego języka. Dodatkowo generateStaticParams zapewnia, że wszystkie kody lokalizacji, które masz aktywowane w swoim projekcie, są wstępnie renderowane.

Teraz zbudujmy naszą pierwszą stronę! Utwórz plik o nazwie /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!" />
	);
}

Zwróć uwagę na zmienną revalidate, która powoduje, że Next.js ponownie zbuduje stronę po 60 sekundach i utrzyma tłumaczenia na bieżąco.

Krok 4: Implementacja renderowania po stronie serwera

TacoTranslate obsługuje renderowanie po stronie serwera. To znacznie poprawia doświadczenie użytkownika, ponieważ przetłumaczona zawartość jest wyświetlana natychmiast, zamiast najpierw pojawiać się krótkie przebłyski nieprzetłumaczonej treści. Dodatkowo możemy pominąć żądania sieciowe po stronie klienta, ponieważ już mamy tłumaczenia potrzebne dla strony, którą użytkownik przegląda.

Aby skonfigurować renderowanie po stronie serwera, utwórz lub zmodyfikuj /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};
};

Dostosuj sprawdzenie isProduction do swojej konfiguracji. Jeśli true, TacoTranslate ujawni publiczny klucz API. Jeśli znajdujemy się w środowisku lokalnym, testowym lub staging (isProduction is false), użyjemy sekretnego klucza API read/write, aby upewnić się, że nowe ciągi znaków zostaną wysłane do tłumaczenia.

Aby upewnić się, że routowanie i przekierowania działają zgodnie z oczekiwaniami, musimy utworzyć plik o nazwie /middleware.ts. Korzystając z Middleware, możemy przekierowywać użytkowników na strony prezentowane w ich preferowanym języku.

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);
}

Upewnij się, że skonfigurujesz matcher zgodnie z dokumentacją Next.js dotyczącą Middleware.

Po stronie klienta możesz zmienić ciasteczko locale, aby ustawić preferowany język użytkownika. Zobacz kompletny przykład kodu, aby dowiedzieć się, jak to zrobić!

Krok 5: Wdróż i przetestuj!

Gotowe! Twoja aplikacja React zostanie teraz automatycznie przetłumaczona, gdy dodasz dowolne ciągi do komponentu Translate. Zwróć uwagę, że tylko środowiska, które mają uprawnienia read/write dla klucza API, będą mogły tworzyć nowe ciągi do przetłumaczenia. Zalecamy posiadanie zamkniętego i zabezpieczonego środowiska staging, w którym możesz przetestować aplikację produkcyjną z takim kluczem API, dodając nowe ciągi przed uruchomieniem na żywo. Zapobiegnie to kradzieży twojego tajnego klucza API przez kogokolwiek oraz potencjalnemu zapychaniu projektu tłumaczeń przez dodawanie nowych, niezwiązanych ciągów.

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 Pages 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!