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

W miarę jak świat staje się coraz bardziej zglobalizowany, coraz ważniejsze staje się, by deweloperzy tworzyli aplikacje, które potrafią obsłużyć 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 samouczku 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 Pages Router.
Jeśli używasz App 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. Jednak w tym przykładzie będziemy używać TacoTranslate.

TacoTranslate automatycznie tłumaczy twoje teksty na dowolny język za pomocą najnowocześniejszej sztucznej inteligencji i uwalnia cię od żmudnego zarządzania plikami JSON.

Zainstalujmy ją za pomocą npm w terminalu:

npm install tacotranslate

Krok 2: Utwórz bezpłatne konto TacoTranslate

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

W interfejsie aplikacji TacoTranslate utwórz projekt i przejdź do zakładki kluczy 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 projektu.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Upewnij się, że nigdy nie ujawnisz tajnego read/write klucza API 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 ciągi tekstowe, na przykład adres URL twojej witryny. Dowiedz się więcej o originach tutaj.

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

Krok 3: Konfigurowanie TacoTranslate

Aby zintegrować TacoTranslate z twoją aplikacją, musisz utworzyć klienta, korzystając z kluczy API podanych wcześniej. 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Wkrótce automatycznie zdefiniujemy TACOTRANSLATE_API_KEY.

Utworzenie klienta w osobnym pliku ułatwia jego późniejsze ponowne użycie. Teraz, korzystając z niestandardowego /pages/_app.tsx, dodamy dostawcę TacoTranslate.

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

Jeśli masz już niestandardowe pageProps i _app.tsx, rozszerz definicję o właściwości i kod przedstawione powyżej.

Krok 4: Implementacja renderowania po stronie serwera

TacoTranslate umożliwia renderowanie po stronie serwera Twoich tłumaczeń. Znacznie poprawia to doświadczenie użytkownika, ponieważ pokazuje przetłumaczoną treść od razu, zamiast najpierw pojawiającego się krótkiego błysku nieprzetłumaczonej zawartości. Dodatkowo możemy pominąć żądania sieciowe po stronie klienta, ponieważ mamy już wszystkie potrzebne tłumaczenia.

Zaczniemy od utworzenia lub modyfikacji /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'),
	});
};

Zmodyfikuj sprawdzenie isProduction tak, aby pasowało do Twojej konfiguracji. Jeśli true, TacoTranslate ujawni publiczny klucz API. Jeśli jesteśmy w środowisku lokalnym, testowym lub staging (isProduction is false), użyjemy sekretnego read/write klucza API, aby upewnić się, że nowe ciągi są wysyłane do tłumaczenia.

Do tej pory skonfigurowaliśmy aplikację Next.js jedynie z listą obsługiwanych języków. Następną rzeczą będzie pobranie tłumaczeń dla wszystkich twoich stron. W tym celu użyjesz albo getTacoTranslateStaticProps albo getTacoTranslateServerSideProps w zależności od wymagań.

Te funkcje przyjmują trzy argumenty: obiekt Next.js Static Props Context, konfigurację dla TacoTranslate oraz opcjonalne właściwości Next.js. Zauważ, że revalidate w getTacoTranslateStaticProps jest domyślnie ustawione na 60, aby Twoje tłumaczenia były aktualne.

Aby użyć którejkolwiek z funkcji na stronie, załóżmy, że masz plik strony taki jak /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!"/>;
}

Powinieneś teraz móc używać komponentu Translate do tłumaczenia ciągów znaków we wszystkich Twoich komponentach React.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Krok 5: Wdróż i przetestuj!

Gotowe! Twoja aplikacja React będzie teraz automatycznie tłumaczona, gdy dodasz jakiekolwiek teksty do komponentu Translate. Zwróć uwagę, że tylko środowiska posiadające uprawnienia read/write dla klucza API będą mogły tworzyć nowe teksty do przetłumaczenia. Zalecamy posiadanie zamkniętego i zabezpieczonego środowiska stagingowego, w którym możesz przetestować swoją aplikację produkcyjną przy użyciu takiego klucza API, dodając nowe teksty przed wdrożeniem na żywo. Zapobiegnie to kradzieży Twojego tajnego klucza API oraz potencjalnemu rozrostowi projektu tłumaczeniowego przez dodawanie nowych, niezwiązanych tekstów.

Koniecznie zobacz pełny przykład na naszym profilu GitHub. Tam znajdziesz także przykład, jak to zrobić używając App Router! Jeśli napotkasz jakiekolwiek problemy, śmiało skontaktuj się z nami, a z przyjemnością pomożemy.

TacoTranslate pozwala automatycznie i szybko lokalizować Twoje aplikacje React do i z ponad 75 języków. Rozpocznij już dziś!