Kaip įgyvendinti internacionalizaciją Next.js programoje, kuri naudoja App Router

Kai pasaulis tampa vis labiau globalizuotas, interneto kūrėjams vis svarbiau kurti programas, galinčias aptarnauti vartotojus iš skirtingų šalių ir kultūrų. Vienas iš pagrindinių būdų tai pasiekti yra internacionalizacija (i18n), kuri leidžia pritaikyti jūsų programą skirtingoms kalboms, valiutoms ir datų formatams.

Šiame straipsnyje aptarsime, kaip pridėti internacionalizaciją prie jūsų React Next.js programos, naudojant serverinį atvaizdavimą. TL;DR: Peržiūrėkite visą pavyzdį čia.

Šis vadovas skirtas Next.js programoms, naudojančioms App Router.
Jei naudojate Pages Router, peržiūrėkite šį vadovą.

1 žingsnis: Įdiekite i18n biblioteką

Norėdami įgyvendinti internacionalizaciją savo Next.js programoje, pirmiausia pasirinkime i18n biblioteką. Yra kelios populiarios bibliotekos, įskaitant next-intl. Tačiau šiame pavyzdyje naudosime TacoTranslate.

TacoTranslate automatiškai verčia jūsų tekstus į bet kurią kalbą naudodamas pažangiausią dirbtinį intelektą ir atlaisvina jus nuo varginančio JSON failų tvarkymo.

Įdiekime ją naudodami npm jūsų terminale:

npm install tacotranslate

2 žingsnis: Sukurkite nemokamą TacoTranslate paskyrą

Dabar, kai įdiegėte modulį, laikas susikurti TacoTranslate paskyrą, vertimo projektą ir susijusius API raktus. Sukurkite paskyrą čia. Tai nemokama ir nereikalauja pridėti kreditinės kortelės.

TacoTranslate programos vartotojo sąsajoje sukurkite projektą ir eikite į jo API raktų skirtuką. Sukurkite vieną read raktą ir vieną read/write raktą. Išsaugosime juos kaip aplinkos kintamuosius. read raktą vadiname public, o read/write raktą — secret. Pavyzdžiui, juos galite pridėti į .env failą savo projekto šakniniame kataloge.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Įsitikinkite, kad niekada neatskleisite slapto read/write API rakto klientinės pusės gamybos aplinkose.

Taip pat pridėsime dar du aplinkos kintamuosius: TACOTRANSLATE_DEFAULT_LOCALE ir TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Numatytasis atsarginis lokalės kodas. Šiame pavyzdyje nustatysime jį į en (anglų).
• TACOTRANSLATE_ORIGIN: „aplankas“, kuriame bus saugomos jūsų teksto eilutės, pavyzdžiui — jūsų svetainės URL. Daugiau apie originus skaitykite čia.

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

3 žingsnis: TacoTranslate nustatymas

Norėdami integruoti TacoTranslate į savo programą, turėsite sukurti klientą naudodami anksčiau minėtus API raktus. Pavyzdžiui, sukurkite failą pavadinimu /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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Netrukus automatiškai nustatysime TACOTRANSLATE_API_KEY ir TACOTRANSLATE_PROJECT_LOCALE.

Kliento sukūrimas atskirame faile palengvina jo pakartotinį naudojimą vėliau. getLocales yra tik pagalbinė funkcija su įmontuotu klaidų tvarkymu. Dabar sukurkite failą pavadinimu /app/[locale]/tacotranslate.tsx, kuriame įgyvendinsime TacoTranslate teikėją.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Atkreipkite dėmesį į 'use client';, nurodantį, kad tai yra kliento pusės komponentas.

Kai konteksto teikėjas jau paruoštas, sukurkite failą pavadinimu /app/[locale]/layout.tsx, mūsų programos pagrindinį išdėstymą. Atkreipkite dėmesį, kad šiame kelyje yra aplankas, naudojantis Dynamic Routes, kuriame [locale] yra dinaminis parametras.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Pirmas dalykas, į kurį reikia atkreipti dėmesį, yra tas, kad mes naudojame mūsų Dynamic Route parametrą [locale] norėdami gauti tos kalbos vertimus. Be to, generateStaticParams užtikrina, kad visi jūsų projekte aktyvinti lokalės kodai būtų iš anksto atvaizduoti.

Dabar sukurkime mūsų pirmąjį puslapį! Sukurkite failą pavadinimu /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Atkreipkite dėmesį į revalidate kintamąjį, kuris nurodo Next.js atnaujinti puslapį po 60 sekundžių ir palaikyti jūsų vertimus naujausius.

4 žingsnis: Serverio pusės renderinimo įgyvendinimas

TacoTranslate palaiko serverinį atvaizdavimą. Tai žymiai pagerina vartotojo patirtį, nes iš karto rodomas išverstas turinys, o ne pirmiausia trumpai pasirodantis neišversto turinio blyksnis. Be to, galime apeiti tinklo užklausas kliento pusėje, nes jau turime vertimus, kurių reikia puslapiui, kurį vartotojas peržiūri.

Norėdami nustatyti serverio pusės atvaizdavimą, sukurkite arba pakeiskite /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Pakoreguokite isProduction patikrinimą pagal savo nustatymus. Jei true, TacoTranslate naudos viešąjį API raktą. Jei esame vietinėje, testavimo arba paruošiamojoje (staging) aplinkoje (isProduction is false), naudosime slaptąjį read/write API raktą, kad naujos eilutės būtų išsiųstos vertimui.

Kad maršrutizavimas ir peradresavimas veiktų tinkamai, turėsime sukurti failą pavadinimu /middleware.ts. Naudodami Middleware, galime peradresuoti vartotojus į puslapius jų pageidaujama kalba.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Įsitikinkite, kad matcher yra sukonfigūruotas pagal Next.js Middleware dokumentaciją.

Kliento pusėje galite pakeisti locale slapuką, kad pakeistumėte vartotojo pageidaujamą kalbą. Peržiūrėkite visą pavyzdinį kodą, kad sužinotumėte, kaip tai padaryti!

Žingsnis 5: Įdiekite ir išbandykite!

Viskas paruošta! Jūsų React programa dabar bus automatiškai išversta, kai į Translate komponentą pridėsite bet kokius tekstus. Pastaba: tik aplinkos, kurioms API raktui suteiktos read/write teisės, galės kurti naujas verčiamas eilutes. Rekomenduojame turėti uždarą ir saugią staging aplinką, kurioje galėtumėte išbandyti savo gamybinę programą su tokio tipo API raktu, pridėdami naujas eilutes prieš paleidžiant į gamybą. Tai apsaugos jūsų slaptą API raktą nuo pavogimo ir neleis jūsų vertimų projektui užsipildyti pridėjus naujas, nesusijusias eilutes.

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 Pages 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!