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 staje się, aby twórcy stron internetowych tworzyli aplikacje, 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 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, zapoznaj się zamiast tego z tym przewodnikiem.

Krok 1: Zainstaluj bibliotekę i18n

Aby wdrożyć internacjonalizację w twojej 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ą, używając 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. To darmowe i nie wymaga podawania danych karty kredytowej.

W interfejsie użytkownika 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 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 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 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 z twoją aplikacją, musisz utworzyć klienta, korzystając z wcześniej podanych kluczy API. 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 oddzielnym 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 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 tłumaczeń po stronie serwera. Znacznie poprawia to doświadczenie użytkownika, ponieważ przetłumaczona zawartość wyświetla się od razu, zamiast najpierw pojawiać się przez chwilę nieprzetłumaczona. Dodatkowo możemy pominąć zapytania 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 kontrolę 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ą wysłane do tłumaczenia.

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

Te funkcje przyjmują trzy argumenty: obiekt Next.js Static Props Context, konfigurację TacoTranslate oraz opcjonalne właściwości Next.js. Zauważ, ż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!"/>;
}

Teraz możesz używać komponentu Translate do tłumaczenia tekstów we wszystkich 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 jakiekolwiek ciągi tekstowe do komponentu Translate. Zauważ, że tylko środowiska, w których klucz API ma uprawnienia read/write, będą mogły tworzyć nowe ciągi do przetłumaczenia. Zalecamy posiadanie zamkniętego i zabezpieczonego środowiska staging, w którym możesz testować aplikację produkcyjną przy użyciu takiego klucza API, dodając nowe ciągi przed uruchomieniem na żywo. Dzięki temu nikt nie będzie mógł ukraść twojego tajnego klucza API ani — potencjalnie — niepotrzebnie rozrosnąć projektu tłumaczeń poprzez dodawanie nowych, niezwiązanych ciągó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!