Kaip įgyvendinti internacionalizaciją Next.js aplikacijoje, naudojančioje App Router

Kaip pasaulis tampa vis labiau globalizuotas, vis svarbiau tampa interneto kūrėjams kurti programas, kurios galėtų aptarnauti vartotojus iš skirtingų šalių ir kultūrų. Vienas iš pagrindinių būdų tai pasiekti yra internacionalizacija (i18n), leidžianti 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 atvaizdavimą. TL;DR: Čia rasite pilną pavyzdį.

Šis vadovas skirtas Next.js programoms, kurios naudoja App Router.
Jei naudojate Pages Router, vietoje to peržiūrėkite šį vadovą.

1 žingsnis: Įdiekite i18n biblioteką

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

TacoTranslate automatiškai išverčia jūsų eilutes į bet kurią kalbą naudodamas pažangiausias DI technologijas ir atlaisvina jus nuo varginančio JSON failų valdymo.

Įdiekime ją naudodami npm savo terminale:

npm install tacotranslate

2 žingsnis: Sukurkite nemokamą TacoTranslate paskyrą

Dabar, kai įdiegėte modulį, pats laikas sukurti savo TacoTranslate paskyrą, vertimo projektą ir susijusius API raktus. Sukurkite paskyrą čia. Tai nemokama, ir nereikia pridėti kredito kortelės.

TacoTranslate programos sąsajoje sukurkite projektą ir eikite į jo API raktų skirtuką. Sukurkite vieną read raktą ir vieną read/write raktą. Juos išsaugosime kaip aplinkos kintamuosius. read raktas yra vadinamas public, o read/write raktas yra secret. Pavyzdžiui, galite juos pridėti į .env failą jūsų projekto šakniniame kataloge.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Įsitikinkite, kad niekada neišsklaidysite slaptų read/write API raktų kliento pusės produkcijos aplinkose.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Numatytoji atsarginė kalbos kodo reikšmė. Š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. Daugiau apie origins skaitykite čia.

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

3 žingsnis: TacoTranslate nustatymas

Norėdami integruoti TacoTranslate su savo programa, turėsite sukurti klientą naudodami ankstesniuose žingsniuose 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;

Mes netrukus automatiškai apibrėšime TACOTRANSLATE_API_KEY ir TACOTRANSLATE_PROJECT_LOCALE.

Kliento kūrimas atskirame faile palengvina jo pakartotinį naudojimą vėliau. getLocales yra tik pagalbinė funkcija su įmontuota klaidų tvarka. 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';, reiškiantį, kad tai yra kliento komponentas.

Kad konteksto teikėjas būtų paruoštas, sukurkite failą pavadinimu /app/[locale]/layout.tsx, kuris yra pagrindinis mūsų programos išdėstymas. 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>
	);
}

Pirmas dalykas, į kurį reikia atkreipti dėmesį, yra tai, kad mes naudojame savo Dynamic Route parametrą [locale] norėdami gauti to kalbos vertimus. Be to, generateStaticParams užtikrina, kad visi lokalės kodai, kuriuos aktyvavote savo projekte, būtų išankstiniai sugeneruoti.

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 per 60 sekundžių perstatyti puslapį ir išlaikyti jūsų vertimus atnaujintus.

4 žingsnis: Serverio pusės atvaizdavimo įgyvendinimas

TacoTranslate palaiko serverio pusės atvaizdavimą. Tai žymiai pagerina vartotojo patirtį, nes iš karto rodomas išverstas turinys, o ne trumpas neišversto turinio blyksnis. Be to, galime išvengti tinklo užklausų kliento pusėje, nes jau turime reikalingus vertimus puslapiui, kurį vartotojas peržiūri.

Norėdami nustatyti serverio pusės atvaizdavimą, sukurkite arba redaguokite /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ų sąranką. Jei true, "TacoTranslate" pateiks viešąjį API raktą. Jei esame vietinėje, bandomojoje ar sustojimo aplinkoje (isProduction is false), naudosime slaptą read/write API raktą, kad įsitikintume, jog naujos eilutės siunčiamos vertimui.

Norint užtikrinti, kad maršrutizavimas ir peradresavimas veiktų tinkamai, 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 nustatėte matcher pagal Next.js Middleware dokumentaciją.

Kliento pusėje galite pakeisti locale slapuką, kad pakeistumėte vartotojo pageidaujamą kalbą. Prašome peržiūrėti pilną pavyzdinį kodą, kad sužinotumėte, kaip tai padaryti!

Žingsnis 5: Diegti ir testuoti!

Mes baigėme! Jūsų React programa dabar bus automatiškai išversta, kai pridėsite bet kokių tekstų į Translate komponentą. Atkreipkite dėmesį, kad tik aplinkos su read/write teisėmis API raktui galės kurti naujus tekstus vertimui. Rekomenduojame turėti uždėtą ir saugią testavimo aplinką, kur galėtumėte išbandyti savo gamybinę programą su tokiu API raktu, pridėdami naujų tekstų prieš paleidžiant į gyvą režimą. Tai apsaugos nuo slapto API rakto pavogimo ir galimo vertimo projekto užpildymo nesusijusiais tekstais.

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!