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

W miarę jak świat staje się coraz bardziej zglobalizowany, dla programistó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 celu jest internacjonalizacja (i18n), która pozwala dostosować aplikację do różnych języków, walut i formatów dat.

W tym samouczku pokażemy, 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 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 użyjemy TacoTranslate.

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

Zainstalujmy go za pomocą npm w terminalu:

npm install tacotranslate

Krok 2: Utwórz darmowe konto TacoTranslate

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

W interfejsie aplikacji TacoTranslate utwórz projekt i przejdź do zakładki z kluczami API. Utwórz jeden read klucz oraz 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 sekretnego klucza API read/write w produkcyjnym środowisku 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 znaków, na przykład adres URL Twojej strony. Przeczytaj 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 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 powyższe właściwości i kod.

Krok 4: Implementacja renderowania po stronie serwera

TacoTranslate umożliwia renderowanie tłumaczeń po stronie serwera. Znacznie poprawia to doświadczenie użytkownika, ponieważ przetłumaczona treść jest wyświetlana 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ż 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'),
	});
};

Zmodyfikuj sprawdzenie isProduction tak, aby pasowało do Twojej 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 mieć pewność, że nowe ciągi znaków zostaną przesłane do tłumaczenia.

Do tej pory skonfigurowaliśmy aplikację Next.js jedynie z listą obsługiwanych języków. Kolejną rzeczą, którą zrobimy, będzie pobranie tłumaczeń dla wszystkich twoich stron. Aby to zrobić, 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 revalidate w getTacoTranslateStaticProps jest domyślnie ustawione na 60, dzięki czemu twoje tłumaczenia pozostają 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!"/>;
}

Teraz powinieneś móc używać komponentu Translate do tłumaczenia ciągów znakó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 dowolne teksty do komponentu Translate. Zwróć uwagę, ż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 stagingowego, w którym możesz przetestować aplikację produkcyjną z takim kluczem API, dodając nowe ciągi przed uruchomieniem na żywo. Dzięki temu nikt nie będzie mógł ukraść Twojego sekretnego klucza API ani potencjalnie doprowadzić do nadmiernego rozrostu projektu tłumaczeń poprzez dodawanie nowych, niezwiązanych ciągów.

Koniecznie zapoznaj się z kompletnym przykładem na naszym profilu GitHub. Tam znajdziesz także 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 umożliwia automatyczną lokalizację Twoich aplikacji React — szybko, do i z ponad 75 języków. Rozpocznij już dziś!