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

Kai pasaulis vis labiau globalėja, interneto kūrėjams tampa vis svarbiau kurti programas, kurios galėtų aptarnauti vartotojus iš skirtingų šalių ir kultūrų. Viena iš pagrindinių priemonių 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 serverio pusės renderinimą. TL;DR: Peržiūrėkite visą pavyzdį čia.

Šis vadovas skirtas Next.js programoms, kurios naudoja App Router.
Jei naudojate Pages Router, žr. vietoj to šį vadovą.

1 žingsnis: Įdiekite i18n biblioteką

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

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

Įdiekime jį naudodami npm savo terminale:

npm install tacotranslate

2 žingsnis: Sukurkite nemokamą TacoTranslate paskyrą

Dabar, kai modulis įdiegtas, pats laikas susikurti TacoTranslate paskyrą, vertimo projektą ir su tuo susijusius API raktus. Sukurkite paskyrą čia. Tai nemokama ir nereikalauja, kad pridėtumėte kreditinę kortelę.

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ą mes vadiname public, o read/write raktas yra secret. Pavyzdžiui, galite juos pridėti prie .env failo projekto šakniniame kataloge.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Būtinai niekada neatskleiskite slaptos read/write API rakto klientinės pusės gamybinėse 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ų kalbai).
• TACOTRANSLATE_ORIGIN: „aplankas“, kuriame bus saugomos jūsų eilutės, pavyzdžiui – jūsų svetainės URL. Daugiau apie originus skaitykite čia.

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

Žingsnis 3: TacoTranslate nustatymas

Norėdami integruoti TacoTranslate su savo programa, turėsite sukurti klientą, naudodami anksčiau gautus 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 apibrėšime TACOTRANSLATE_API_KEY ir TACOTRANSLATE_PROJECT_LOCALE.

Kliento sukūrimas atskirame faile palengvina jo pakartotinį naudojimą vėliau. getLocales yra tik pagalbinė funkcija su keliais įmontuotais klaidų tvarkymo mechanizmais. Dabar sukurkite failą pavadinimu /app/[locale]/tacotranslate.tsx, kuriame įdiegsime TacoTranslate tiekė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';. Tai nurodo, kad tai yra kliento komponentas.

Dabar, kai konteksto teikėjas 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, kur [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>
	);
}

Pirmiausia reikia atkreipti dėmesį, kad čia naudojame mūsų Dynamic Route parametrą [locale] norėdami gauti šios kalbos vertimus. Be to, generateStaticParams užtikrina, kad visi jūsų projekte aktyvuoti lokalės kodai būtų iš anksto sugeneruoti.

Dabar sukurkime savo 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 po 60 sekundžių iš naujo sugeneruoti puslapį ir palaikyti jūsų vertimus atnaujintais.

4 žingsnis: Serverio pusės renderinimo įgyvendinimas

TacoTranslate palaiko serverio pusės atvaizdavimą. Tai gerokai pagerina vartotojo patirtį — iš karto rodomas išverstas turinys, o ne pirmiausia pasirodantis trumpas neišverstų tekstų blyksnis. Be to, klientinėje pusėje galime išvengti tinklo užklausų, nes jau turime vertimus, reikalingus puslapiui, kurį vartotojas ž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};
};

Pakeiskite isProduction patikrinimą, kad jis atitiktų jūsų nustatymus. Jei true, TacoTranslate naudos viešąjį API raktą. Jei esame vietinėje, testinėje arba parengiamojoje aplinkoje (isProduction is false), mes naudosime slaptąjį read/write API raktą, kad naujos eilutės būtų išsiųstos vertimui.

Kad maršrutavimas ir peradresavimas veiktų kaip tikimasi, turėsime sukurti failą pavadinimu /middleware.ts. Naudodami Middleware, galime peradresuoti vartotojus į puslapius, pateikiamus 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 nustatytas pagal Next.js Middleware dokumentaciją.

Kliento pusėje galite pakeisti locale slapuką, kad pakeistumėte vartotojo pageidaujamą kalbą. Peržiūrėkite pilną pavyzdinį kodą, kad gautumėte idėjų, kaip tai padaryti!

5-asis žingsnis: Įdiekite ir išbandykite!

Viskas paruošta! Jūsų React programėlė dabar bus automatiškai išversta, kai į Translate komponentą pridėsite bet kokių tekstų. Atkreipkite dėmesį, kad tik tos aplinkos, kurioms API rakto teisės yra read/write, galės kurti naujas vertimui skirtas eilutes. Rekomenduojame turėti uždarą ir saugią parengiamąją (staging) aplinką, kurioje galėtumėte išbandyti savo produkcinę programą su tokio tipo API raktu ir pridėti naujas eilutes prieš paleidžiant. Tai apsaugos jūsų slaptą API raktą nuo pavogimo ir padės išvengti jūsų vertimų projekto užpildymo nereikalingomis, nesusijusiomis eilutėmis.

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!