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

W miarę jak świat staje się coraz bardziej zglobalizowany, dla deweloperów stron internetowych coraz ważniejsze staje się tworzenie aplikacji, które mogą obsługiwać 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 wykorzystaniem renderowania po stronie serwera. TL;DR: Zobacz tutaj pełny przykład.

Ten przewodnik jest przeznaczony dla 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 zaimplementować internacjonalizację w swojej aplikacji Next.js, najpierw wybierzemy bibliotekę i18n. Istnieje kilka popularnych bibliotek, w tym next-intl. W tym przykładzie jednak użyjemy TacoTranslate.

TacoTranslate automatycznie tłumaczy Twoje teksty na dowolny język, wykorzystując najnowocześniejszą sztuczną inteligencję, i uwalnia Cię od żmudnego zarządzania plikami JSON.

Zainstalujmy ją przy użyciu npm w terminalu:

npm install tacotranslate

Krok 2: Utwórz darmowe konto TacoTranslate

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

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

Dodamy również dwie dodatkowe zmienne środowiskowe: TACOTRANSLATE_DEFAULT_LOCALE oraz 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 internetowej. Przeczytaj więcej o origins tutaj.

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

Krok 3: Konfiguracja TacoTranslate

Aby zintegrować TacoTranslate z twoją aplikacją, musisz utworzyć klienta, używając kluczy API z wcześniejszych kroków. 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 oraz TACOTRANSLATE_PROJECT_LOCALE.

Utworzenie klienta w osobnym pliku ułatwia jego ponowne użycie później. getLocales to po prostu 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';, co wskazuje, że jest to komponent po stronie klienta.

Teraz, gdy dostawca 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 zawiera 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 zauważyć, jest to, że używamy naszego parametru Dynamic Route [locale], aby pobrać tłumaczenia dla tego języka. Dodatkowo, generateStaticParams zapewnia, że wszystkie kody lokalizacji, które aktywowałeś w swoim projekcie, są prerenderowane.

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 informuje Next.js, aby przebudował stronę po 60 sekundach i utrzymał Twoje tłumaczenia na bieżąco.

Krok 4: Implementacja renderowania po stronie serwera

TacoTranslate obsługuje renderowanie po stronie serwera. Znacznie poprawia to doświadczenie użytkownika, pokazując od razu przetłumaczoną zawartość, zamiast najpierw wyświetlać chwilę nieprzetłumaczonej treści. Dodatkowo możemy pominąć żądania sieciowe po stronie klienta, ponieważ już mamy tłumaczenia potrzebne do strony, którą użytkownik przegląda.

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

Zmodyfikuj sprawdzenie isProduction zgodnie z Twoją konfiguracją. Jeśli true, TacoTranslate udostępni publiczny klucz API. Jeśli znajdujemy się w środowisku lokalnym, testowym lub staging (isProduction is false), użyjemy sekretnego klucza API read/write aby mieć pewność, że nowe ciągi znaków zostaną wysłane do tłumaczenia.

Aby zapewnić poprawne działanie routingu i przekierowań, musimy utworzyć plik o nazwie /middleware.ts. Korzystając z Middleware, możemy przekierować użytkowników na strony wyświetlane 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 matcher jest skonfigurowany zgodnie z dokumentacją Next.js Middleware.

Po stronie klienta możesz zmienić wartość ciasteczka locale, aby zmienić preferowany język użytkownika. Zobacz pełny przykład kodu, aby uzyskać pomysły, jak to zrobić!

Krok 5: Wdróż i przetestuj!

Skończyliśmy! Twoja aplikacja React będzie teraz automatycznie tłumaczona, gdy dodasz dowolne ciągi tekstowe do komponentu Translate. Zauważ, że tylko środowiska z uprawnieniami read/write na kluczu 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 testować swoją produkcyjną aplikację z takim kluczem API, dodając nowe ciągi przed uruchomieniem na żywo. Zabezpieczy to przed kradzieżą Twojego sekretnego klucza API i potencjalnym rozrostem projektu tłumaczeniowego 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!