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

Jak to działa

W miarę jak świat staje się coraz bardziej zglobalizowany, coraz ważniejsze jest dla twórców stron internetowych tworzenie aplikacji, które mogą obsługiwać użytkowników z różnych krajów i kultur. Jednym z kluczowych sposobów na osiągnięcie 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, zapoznaj się zamiast tego z tym przewodnikiem.

Krok 1: Zainstaluj bibliotekę i18n

Aby zaimplementować 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, wykorzystując nowoczesną sztuczną inteligencję, i uwalnia Cię od żmudnego zarządzania plikami JSON.

Zainstalujmy ją za pomocą npm w Twoim terminalu:

npm install tacotranslate

Krok 2: Utwórz darmowe konto TacoTranslate

Teraz, gdy masz już 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 aplikacji TacoTranslate utwórz projekt i przejdź do zakładki z kluczami API. Utwórz jeden klucz read, oraz 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 swojego 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 także 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, czyli angielski.
• TACOTRANSLATE_ORIGIN: „Folder”, w którym będą przechowywane Twoje ciągi znaków, na przykład adres URL Twojej strony internetowej. Czytaj 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 utworzonych kluczy API. 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.

Tworzenie klienta w osobnym pliku ułatwia ponowne jego użycie później. 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 oraz _app.tsx, prosimy rozbudować definicję o właściwości i kod podane powyżej.

Krok 4: Implementacja renderowania po stronie serwera

TacoTranslate umożliwia renderowanie tłumaczeń po stronie serwera. Znacznie poprawia to doświadczenie użytkownika, wyświetlając od razu przetłumaczoną treść, zamiast najpierw pokazywać krótkotrwały, nietłumaczony materiał. 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'),
	});
};

Zmodyfikuj test isProduction , aby dopasować go do swojej konfiguracji. Jeśli true, TacoTranslate wyświetli publiczny klucz API. Jeśli znajdujemy się w środowisku lokalnym, testowym lub testowym (isProduction is false), użyjemy klucza tajnego read/write API, aby upewnić się, że nowe ciągi są wysyłane do tłumaczenia.

Do tej pory skonfigurowaliśmy aplikację Next.js tylko z listą obsługiwanych języków. Następną rzeczą, którą zrobimy, jest pobranie tłumaczeń dla wszystkich Twoich stron. Aby to zrobić, użyjesz albo getTacoTranslateStaticProps, albo getTacoTranslateServerSideProps w zależności od swoich potrzeb.

Te funkcje przyjmują trzy argumenty: jeden obiekt Next.js Static Props Context, konfigurację dla TacoTranslate oraz opcjonalne właściwości Next.js. Zauważ, że revalidate w getTacoTranslateStaticProps jest domyślnie ustawione na 60, aby Twoje tłumaczenia były na bieżąco.

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!

Skończyliśmy! 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 do klucza API będą mogły tworzyć nowe teksty do przetłumaczenia. Zalecamy posiadanie zamkniętego i zabezpieczonego środowiska stagingowego, w którym możesz testować swoją aplikację produkcyjną z takim kluczem API, dodając nowe teksty przed uruchomieniem na żywo. Zapobiegnie to kradzieży twojego sekretnego klucza API oraz potencjalnemu rozdmuchaniu projektu tłumaczeń poprzez dodanie 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!