Jak wdrożyć internacjonalizację w aplikacji Next.js korzystającej z Pages Router

W miarę jak świat staje się coraz bardziej zunifikowany, coraz ważniejsze dla programistów stron internetowych jest tworzenie aplikacji, które mogą zaspokoić potrzeby 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 omówimy, jak dodać internacjonalizację do Twojej aplikacji React Next.js, z renderowaniem po stronie serwera. TL;DR: Zobacz tutaj pełny przykład.

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 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 najnowocześniejszą 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 w TacoTranslate, projekt tłumaczeniowy oraz powiązane klucze API. Utwórz konto tutaj. To bezpłatne i nie wymaga podawania 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. Zapisz 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 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 ciągi znaków, na przykład adres URL Twojej strony internetowej. Przeczytaj więcej o origins tutaj.

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

Krok 3: Konfiguracja TacoTranslate

Aby zintegrować TacoTranslate z Twoją aplikacją, musisz utworzyć klienta, używając wcześniej uzyskanych 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 jego ponowne użycie 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, prosimy o rozszerzenie definicji o właściwości i kod podane 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ą zawartość natychmiast, zamiast najpierw wyświetlać krótkie migawki nieprzetłumaczonej treści. Dodatkowo możemy pominąć żądania sieciowe po stronie klienta, ponieważ już posiadamy wszystkie potrzebne tłumaczenia.

Zacznijmy 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. Następnym 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.

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 wartość revalidate w getTacoTranslateStaticProps jest domyślnie ustawiona 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ś być w stanie 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!

Ukończyliśmy! Twoja aplikacja React będzie teraz automatycznie tłumaczona, gdy dodasz jakiekolwiek ciągi znaków do komponentu Translate. Zauważ, że tylko środowiska z uprawnieniami read/write do klucza 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 testować swoją produkcyjną aplikację z takim kluczem API, dodając nowe ciągi przed uruchomieniem na żywo. Zapobiegnie to kradzieży twojego sekretnego klucza API oraz potencjalnemu nadmiernemu rozrostowi projektu tłumaczeń przez dodawanie nowych, niezwiązanych ciągów.

Upewnij się, że zapoznałeś się z kompletnym przykładem na naszym profilu GitHub. Znajdziesz tam również przykład, jak to zrobić, używając App Router! Jeśli napotkasz jakiekolwiek problemy, śmiało skontaktuj się z nami, a chętnie pomożemy.

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