Najlepsze rozwiązanie do internacjonalizacji (i18n) w aplikacjach Next.js

Jak to działa

W miarę jak świat staje się coraz bardziej zglobalizowany, coraz ważniejsze jest, aby deweloperzy stron internetowych 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 przyjrzymy się, 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 korzystasz z App Router, zobacz zamiast tego ten przewodnik.

Krok 1: Zainstaluj bibliotekę i18n

Aby wprowadzić internacjonalizację do 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 teksty na dowolny język za pomocą najnowocześniejszej sztucznej inteligencji i uwalnia cię od żmudnego zarządzania plikami JSON.

Zainstalujmy go przy użyciu npm w terminalu:

npm install tacotranslate

Krok 2: Utwórz darmowe konto TacoTranslate

Teraz, gdy masz zainstalowany moduł, czas utworzyć konto TacoTranslate, projekt tłumaczeniowy oraz powiązane klucze API. Utwórz konto tutaj. Jest darmowe i nie wymaga podania 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 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 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 witryny. Więcej informacji o originach znajdziesz 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 ponowne wykorzystanie w przyszłości. 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 już posiadasz 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, pokazując przetłumaczoną treść od razu, zamiast chwilowego wyświetlenia 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 odpowiadało Twojej konfiguracji. Jeśli true, TacoTranslate udostępni publiczny klucz API. Jeśli znajdujemy się 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ą wysłane do tłumaczenia.

Do tej pory skonfigurowaliśmy aplikację Next.js tylko z listą obsługiwanych języków. Kolejnym krokiem będzie pobranie tłumaczeń dla wszystkich twoich stron. Aby to zrobić, użyjesz albo getTacoTranslateStaticProps albo getTacoTranslateServerSideProps w zależności od twoich potrzeb.

Funkcje te 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 ustawione domyślnie 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!"/>;
}

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 Next.js będzie teraz automatycznie tłumaczona, gdy dodasz dowolne teksty do komponentu Translate. Zwróć uwagę, że tylko środowiska z uprawnieniami read/write dla klucza API będą mogły tworzyć nowe ciągi przeznaczone do tłumaczenia. Zalecamy posiadanie zamkniętego i zabezpieczonego środowiska staging, w którym możesz przetestować swoją aplikację produkcyjną przy użyciu takiego klucza API, dodając nowe teksty przed jej uruchomieniem na żywo. To zapobiegnie komukolwiek kradzieży twojego tajnego klucza API i potencjalnemu rozrostowi projektu tłumaczeń poprzez dodawanie nowych, niezwiązanych tekstów.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!