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 staje się coraz ważniejsze 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 Twojej aplikacji React Next.js z renderowaniem po stronie serwera. TL;DR: Zobacz pełny przykład tutaj.

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 Twojej 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 ciągi znaków na dowolny język, korzystając z najnowocześniejszej sztucznej inteligencji, i uwalnia Cię od żmudnego zarządzania plikami JSON.

Zainstalujmy ją, używając npm w Twoim terminalu:

npm install tacotranslate

Krok 2: Utwórz darmowe konto TacoTranslate

Teraz, gdy masz już zainstalowany moduł, czas założyć konto TacoTranslate, projekt tłumaczeniowy oraz 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 klucz read i 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 ujawnisz sekretnego klucza API read/write w środowiskach produkcyjnych po stronie klienta.

Dodamy również dwie kolejne zmienne środowiskowe: TACOTRANSLATE_DEFAULT_LOCALE oraz TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Domyślny kod języka zapasowego. W tym przykładzie ustawimy go na en dla języka angielskiego.
• TACOTRANSLATE_ORIGIN: „folder”, w którym będą przechowywane twoje ciągi znaków, na przykład URL twojej strony internetowej. Przeczytaj więcej o originach tutaj.

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

Krok 3: Konfiguracja TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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.

Tworzenie klienta w osobnym pliku ułatwia jego ponowne wykorzystanie później. getLocales to tylko funkcja pomocnicza z wbudowanym obsługiwaniem 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'; wskazujące, że jest to komponent klienta.

Z przygotowanym już dostawcą kontekstu, utwórz plik o nazwie /app/[locale]/layout.tsx, który będzie głównym układem w naszej aplikacji. Zauważ, że ta ścieżka zawiera folder wykorzystujący Dynamic Routes, gdzie [locale] jest dynamicznym parametrem.

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] do pobierania tłumaczeń dla tego języka. Dodatkowo, generateStaticParams zapewnia, że wszystkie kody lokalizacji, które aktywowałeś w swoim projekcie, są pre-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 informuje Next.js, aby przebudował stronę po 60 sekundach i utrzymywał 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 przetłumaczone treści natychmiast, zamiast najpierw migać zawartością nieprzetłumaczoną. Dodatkowo, możemy pominąć żądania sieciowe po stronie klienta, ponieważ już mamy potrzebne tłumaczenia dla 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 test isProduction , aby dopasować go do swojej konfiguracji. Jeśli true, TacoTranslate wyświetli publiczny klucz API. Jeśli znajdujemy się w środowisku lokalnym, testowym lub testowym (isProduction is false), użyjemy klucza tajnego read/write API, aby upewnić się, że nowe ciągi są wysyłane do tłumaczenia.

Aby zapewnić prawidłowe działanie routingu i przekierowań, będziemy musieli stworzyć plik o nazwie /middleware.ts. Korzystając z Middleware, możemy przekierowywać 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 ustawiasz matcher zgodnie z dokumentacją Next.js Middleware.

Po stronie klienta możesz zmienić wartość ciasteczka locale, aby zmienić preferowany język użytkownika. Proszę 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 jakiekolwiek ciągi do komponentu Translate. Zauważ, że tylko środowiska posiadające uprawnienia read/write dla klucza API będą mogły tworzyć nowe ciągi do tłumaczenia. Zalecamy posiadanie zamkniętego i zabezpieczonego środowiska staging, w którym możesz przetestować swoją aplikację produkcyjną z takim kluczem API, dodając nowe ciągi przed uruchomieniem na żywo. Zapobiegnie to kradzieży Twojego sekretnego klucza API oraz potencjalnemu nadmiernemu rozrostowi Twojego projektu tłumaczeń przez dodawanie nowych, niezwiązanych ciągów.

Upewnij się, że zapoznałeś się z pełnym przykładem na naszym profilu GitHub. Znajdziesz tam również przykład, jak to zrobić za pomocą Pages Router ! Jeśli napotkasz jakiekolwiek problemy, śmiało skontaktuj się z nami, a chętnie pomożemy.

TacoTranslate pozwala szybko automatycznie lokalizować Twoje aplikacje React na dowolny język i z dowolnego języka. Rozpocznij już dziś!