Jak zaimplementować internacjonalizację w aplikacji Next.js używającej Pages Router

W miarę jak świat staje się bardziej zglobalizowany, coraz ważniejsze jest, aby deweloperzy webowi tworzyli aplikacje odpowiadające użytkownikom 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 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 dotyczy aplikacji Next.js korzystających z Pages Router.
Jeśli używasz App Router, zapoznaj się zamiast tego z tym przewodnikiem.

Krok 1: Zainstaluj bibliotekę i18n

Aby zaimplementować internacjonalizację w 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 przy użyciu 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 zainstalowany moduł, czas utworzyć konto TacoTranslate, projekt tłumaczeniowy oraz powiązane klucze API. Załóż konto tutaj. To darmowe i nie wymaga podawania karty kredytowej.

W interfejsie aplikacji TacoTranslate utwórz projekt i przejdź do zakładki kluczy API. Utwórz jeden read klucz i jeden read/write klucz. Zapiszemy je jako zmienne środowiskowe. Klucz read nazywamy public, a klucz read/write nazywamy 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 produkcyjnych środowiskach 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. Dowiedz się więcej o originach tutaj.

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

Krok 3: Konfigurowanie TacoTranslate

Aby zintegrować TacoTranslate ze swoją aplikacją, musisz utworzyć klienta przy użyciu kluczy API z wcześniejszych kroków. Na przykład stwó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, rozszerz definicję o właściwości i kod podane powyżej.

Krok 4: Wdrażanie renderowania po stronie serwera

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

Dostosuj sprawdzenie isProduction do swojej konfiguracji. Jeśli true, TacoTranslate udostępni publiczny klucz API. Jeśli jesteśmy w środowisku lokalnym, testowym lub stagingowym (isProduction is false), użyjemy sekretnego klucza API read/write, aby upewnić się, ż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. Kolejnym krokiem będzie pobranie tłumaczeń dla wszystkich twoich stron. Aby to zrobić, użyj albo getTacoTranslateStaticProps albo getTacoTranslateServerSideProps w zależności od wymagań.

Te funkcje przyjmują trzy argumenty: obiekt Next.js Static Props Context, konfigurację TacoTranslate oraz opcjonalne właściwości Next.js. Zauważ, że revalidate w getTacoTranslateStaticProps jest domyślnie ustawione 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żyć komponentu Translate do tłumaczenia ciągów tekstowych 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 ciągi tekstowe do komponentu Translate. Zauważ, że tylko środowiska posiadające uprawnienia 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 przetestować aplikację produkcyjną z takim kluczem API, dodając nowe ciągi przed uruchomieniem. To zapobiegnie kradzieży Twojego tajnego klucza API oraz potencjalnemu rozrostowi projektu tłumaczeń przez dodawanie nowych, niezwiązanych ciągów.

Koniecznie sprawdź kompletny 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 chętnie pomożemy.

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