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

Kai pasaulis tampa vis labiau globalizuotas, interneto kūrėjams vis svarbiau kurti programas, pritaikytas vartotojams 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ą jūsų React Next.js programai su serverio pusės atvaizdavimu. TL;DR: Peržiūrėkite visą pavyzdį čia.

Šis vadovas skirtas Next.js programoms, kurios naudoja 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 mes naudosime TacoTranslate.

TacoTranslate automatiškai išverčia jūsų eilutes į bet kurią kalbą pasitelkdamas pažangiausią dirbtinį intelektą ir atleidžia 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 modulis įdiegtas, laikas sukurti TacoTranslate paskyrą, vertimų projektą ir susijusius API raktus. Sukurkite paskyrą čia. Tai nemokama ir nereikia pridėti kredito kortelės.

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Įsitikinkite, kad niekada neatskleiskite slapto read/write API rakto kliento 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 jį nustatysime kaip en anglų kalbai.
• TACOTRANSLATE_ORIGIN: „aplankas“, kuriame bus saugomos jūsų eilutės, pavyzdžiui, jūsų svetainės URL. Skaitykite daugiau apie originus č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 pateiktus 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 kūrimas atskirame faile palengvina jo pakartotinį panaudojimą vėliau. getLocales yra tik pagalbinė funkcija su keliais įmontuotais klaidų tvarkymo mechanizmais. 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';, kuris nurodo, kad tai yra kliento komponentas.

Dabar, kai konteksto teikėjas paruoštas, sukurkite failą pavadinimu /app/[locale]/layout.tsx, kuris yra mūsų programos pagrindinis išdėstymas. Atkreipkite dėmesį, kad šiame kelyje yra aplankas, kuriame naudojamos 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 verta atkreipti dėmesį, kad čia naudojame savo Dynamic Route parametrą [locale] tam, kad gautume vertimus toje kalboje. Be to, generateStaticParams užtikrina, kad visi jūsų projekte suaktyvinti lokalės kodai būtų iš anksto sugeneruoti.

Dabar sukurkime 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 iš naujo sugeneruoti puslapį po 60 sekundžių ir užtikrina, kad jūsų vertimai būtų atnaujinti.

4 žingsnis: Serverio pusės renderinimo įgyvendinimas

TacoTranslate palaiko serverio pusės atvaizdavimą. Tai ženkliai pagerina vartotojo patirtį, nes verčiamas turinys rodomas iš karto, o ne pirmiausia trumpam pasirodo neišverstas turinys. Be to, galime praleisti tinklo užklausas kliento pusėje, nes jau turime vertimus, reikalingus puslapiui, kurį vartotojas peržiūri.

Norėdami nustatyti serverinį 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};
};

Pritaikykite isProduction patikrinimą prie savo nustatymų. Jei true, TacoTranslate pateiks viešąjį API raktą. Jei esame vietinėje, testinėje arba staging aplinkoje (isProduction is false), naudosime slaptąjį read/write API raktą, kad įsitikintume, jog nauji tekstai siunčiami vertimui.

Kad maršrutizavimas ir peradresavimas veiktų kaip tikėtasi, turėsime sukurti failą pavadinimu /middleware.ts. Naudodami Middleware, galime nukreipti vartotojus į jų pageidaujamos kalbos puslapius.

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 sukonfigūruotas pagal Next.js Middleware dokumentaciją.

Kliento pusėje galite pakeisti locale slapuką, kad pakeistumėte vartotojo pageidaujamą kalbą. Norėdami sužinoti, kaip tai padaryti, peržiūrėkite pilną pavyzdinį kodą!

5 žingsnis: Įdiekite ir išbandykite!

Viskas paruošta! Jūsų React programa dabar bus automatiškai išversta, kai pridėsite bet kokius tekstus į Translate komponentą. Atkreipkite dėmesį, kad tik aplinkos, kurioms API raktas suteikia read/write teises, galės sukurti naujas eilutes vertimui. Rekomenduojame turėti uždarą ir apsaugotą parengimo (staging) aplinką, kurioje galėtumėte testuoti savo gamybinę programą naudodami tokio tipo API raktą, pridėdami naujas eilutes prieš paleidžiant ją. Tai neleis niekam niekam pavogti jūsų slaptą API raktą ir potencialiai išpūsti jūsų vertimų projektą 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!