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

W miarę jak świat staje się coraz bardziej zglobalizowany, dla twórcó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 daty.

W tym samouczku pokażemy, jak dodać internacjonalizację do 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 Pages Router.
Jeśli korzystasz z App 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. Jednak w tym przykładzie będziemy korzystać z TacoTranslate.

TacoTranslate automatycznie tłumaczy twoje teksty na dowolny język, wykorzystując nowoczesną sztuczną inteligencję, 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 i 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 read klucz oraz jeden read/write klucz. Zapiszemy je jako zmienne środowiskowe. Klucz read nazywamy public, a klucz read/write jest 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 sekretnego klucza API read/write w środowiskach produkcyjnych po stronie klienta.

Dodamy też 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 witryny. Dowiedz się więcej o originach tutaj.

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

Krok 3: Konfiguracja TacoTranslate

Aby zintegrować TacoTranslate ze swoją aplikacją, musisz utworzyć klienta, korzystając z kluczy API utworzonych 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 ponowne użycie później. Teraz, używając 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, proszę rozszerzyć definicję o właściwości i kod podany powyżej.

Krok 4: Wdrażanie renderowania po stronie serwera

TacoTranslate umożliwia renderowanie po stronie serwera Twoich tłumaczeń. Zdecydowanie poprawia to doświadczenie użytkownika, wyświetlając przetłumaczoną zawartość od razu, zamiast najpierw krótkiego mignięcia nieprzetłumaczonej treści. Dodatkowo możemy pominąć żądania sieciowe po stronie klienta, ponieważ już mamy 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'),
	});
};

Dostosuj sprawdzenie isProduction do swojej 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 klucza API read/write, aby upewnić się, że nowe teksty zostaną wysłane do tłumaczenia.

Do tej pory skonfigurowaliśmy aplikację Next.js tylko z listą obsługiwanych języków. Kolejną rzeczą, którą zrobimy, jest pobranie tłumaczeń dla wszystkich stron. W tym celu użyjesz albo getTacoTranslateStaticProps albo getTacoTranslateServerSideProps w zależności od swoich wymagań.

Te funkcje przyjmują trzy argumenty: obiekt Next.js Static Props Context, konfigurację dla TacoTranslate oraz opcjonalne właściwości Next.js. Zwróć uwagę, że wartość revalidate w getTacoTranslateStaticProps jest domyślnie ustawiona na 60, dzięki czemu twoje tłumaczenia pozostają aktualne.

Aby użyć którejkolwiek z tych 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 tekstów we wszystkich swoich 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, w których klucz API ma uprawnienia read/write, będą mogły tworzyć nowe teksty do przetł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 teksty przed uruchomieniem na żywo. Zapobiegnie to temu, że ktoś ukradnie Twój tajny klucz API i potencjalnie zaśmieci projekt tłumaczeń, dodając nowe, niezwiązane teksty.

Koniecznie sprawdź pełny przykład na naszym profilu GitHub. Znajdziesz tam również przykład, jak to zrobić przy użyciu App Router! Jeśli napotkasz jakiekolwiek problemy, śmiało skontaktuj się z nami, a z przyjemnością pomożemy.

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