Jak zaimplementować internacjonalizację w aplikacji Next.js korzystającej z Pages Router

W miarę jak świat staje się coraz bardziej zglobalizowany, dla twórców stron internetowych rośnie znaczenie tworzenia 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 jest internacjonalizacja (i18n), która pozwala dostosować aplikację do różnych języków, walut i formatów dat.

W tym poradniku omówimy, jak dodać internacjonalizację do Twojej aplikacji React Next.js z wykorzystaniem renderowania po stronie serwera. TL;DR: Zobacz pełny przykład tutaj.

Ten przewodnik jest przeznaczony dla aplikacji Next.js, które korzystają z Pages Router.
Jeśli używasz App Router, zobacz zamiast tego ten przewodnik.

Krok 1: Zainstaluj bibliotekę i18n

Aby zaimplementować internacjonalizację w 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, korzystając z najnowszej 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 darmowe konto TacoTranslate

Teraz, gdy masz już zainstalowany moduł, czas na założenie konta TacoTranslate, utworzenie projektu tłumaczeniowego oraz powiązanych kluczy API. Załóż konto tutaj. To darmowe 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 ujawniasz 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 języka zapasowego. W tym przykładzie ustawimy go na en dla angielskiego.
• TACOTRANSLATE_ORIGIN: „Folder”, w którym będą przechowywane Twoje teksty, na przykład adres URL Twojej strony internetowej. Przeczytaj więcej o originach tutaj.

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

Krok 3: Konfiguracja TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 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 i _app.tsx, prosimy o rozszerzenie definicji o właściwości i kod z powyższego.

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 od razu przetłumaczoną treść, zamiast najpierw migać niezlokalizowaną zawartością. Dodatkowo możemy pominąć wywołania sieciowe po stronie klienta, ponieważ już posiadamy wszystkie potrzebne tłumaczenia.

Zaczniemy od utworzenia lub modyfikacji pliku /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 getTacoTranslateStaticProps lub getTacoTranslateServerSideProps w zależności od swoich wymagań.

Te funkcje przyjmują trzy argumenty: obiekt One Next.js Static Props Context , konfigurację dla TacoTranslate i opcjonalne właściwości Next.js. Pamiętaj, że opcja revalidate na getTacoTranslateStaticProps jest domyślnie ustawiona na 60, dzięki czemu tłumaczenia są 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 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 dowolne ciągi tekstowe do komponentu Translate. Zauważ, że tylko środowiska z uprawnieniami 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 testować swoją aplikację produkcyjną z takim kluczem API, dodając nowe ciągi przed jej uruchomieniem na żywo. Zapobiegnie to kradzieży Twojego tajnego klucza API oraz potencjalnemu nadmiernemu rozrostowi projektu tłumaczeń przez dodawanie nowych, niezwiązanych ciągów.

Koniecznie sprawdź pełny przykład na naszym profilu GitHub. Znajdziesz tam również przykład, jak zrobić to z użyciem App Router! Jeśli napotkasz jakiekolwiek problemy, śmiało skontaktuj się z nami, z przyjemnością pomożemy.

TacoTranslate pozwala na szybkie automatyczne lokalizowanie Twoich aplikacji React do i z dowolnego języka. Rozpocznij już dziś!