Kaip įgyvendinti lokalizaciją Next.js programoje, naudojančioje App Router

Kadangi pasaulis tampa vis labiau globalizuotas, interneto kūrėjams vis svarbiau kurti programas, kurios gali patenkinti 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 datos formatams.

Šiame straipsnyje nagrinėsime, kaip pridėti internacionalizaciją prie jūsų React Next.js programos su serverio pusės atvaizdavimu. TL;DR: Peržiūrėkite visą pavyzdį čia.

Ši instrukcija skirta Next.js programoms, kurios naudoja App Router.
Jei naudojate Pages Router, žiūrėkite šią instrukciją.

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 mes naudosime TacoTranslate.

TacoTranslate automatiškai išverčia jūsų tekstus į bet kurią kalbą naudodama pažangią AI technologiją ir atlaisvina jus nuo nuobodaus JSON failų valdymo.

Įdiekime ją naudodami npm savo terminale:

npm install tacotranslate

2 žingsnis: Susikurkite nemokamą TacoTranslate paskyrą

Dabar, kai modulis įdiegtas, atėjo laikas susikurti savo TacoTranslate paskyrą, vertimo projektą ir susijusius API raktus. Sukurti paskyrą čia. Tai nemokama, ir nereikalauja 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ą. Juos išsaugosime kaip aplinkos kintamuosius. read raktas vadinamas public, o read/write raktas yra secret. Pavyzdžiui, juos galima pridėti į .env failą projekto šaknyje.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Įsitikinkite, kad niekada nepateksite į viešumą slaptąjį read/write API raktą klientinėje gamybos aplinkoje.

Taip pat pridėsime dar dvi aplinkos kintamąsias: TACOTRANSLATE_DEFAULT_LOCALE ir TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Numatytoji atsarginė lokalės reikšmė. Šiame pavyzdyje ją nustatysime į en anglų kalbai.
• TACOTRANSLATE_ORIGIN: „Katalogas“, kuriame bus saugomi jūsų tekstai, 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

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_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į naudojimą ateityje. getLocales yra paprasta pagalbinė funkcija su įtaisytu klaidų valdymu. Dabar sukurkite failą, pavadintą /app/[locale]/tacotranslate.tsx, kuriame įgyvendinsime 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';, nurodantį, 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>
	);
}

Pirmiausia reikia atkreipti dėmesį, kad naudojame mūsų Dynamic Route parametrą [locale], kad gautume to kalbos vertimus. Be to, generateStaticParams užtikrina, kad visi jūsų projekte suaktyvinti lokalės kodai 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 atnaujinti vertimus.

4 žingsnis: Serverio pusės pateikimo įgyvendinimas

TacoTranslate palaiko serverio pusės renderinimą. Tai žymiai pagerina vartotojo patirtį, nes iškart rodomas išverstas turinys, o ne pirmiausia trumpas nevertinto turinio blyksnis. Be to, galime praleisti tinklo užklausas kliento pusėje, nes jau turime vertimus, kurių reikia vartotojui peržiūrint puslapį.

Norėdami nustatyti serverio pusės atvaizdavimą, sukurkite arba modifikuokite /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.

Kad užtikrintume, jog maršrutizavimas ir peradresavimas veikia tinkamai, turėsime sukurti failą pavadinimu /middleware.ts. Naudodami Middleware, galime nukreipti naudotojus į puslapius, pateiktus 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 nustatytas pagal Next.js Middleware dokumentaciją.

Klientinėje pusėje galite pakeisti locale slapuką, kad pakeistumėte vartotojo pageidaujamą kalbą. Prašome peržiūrėti pilną pavyzdžio kodą, kad gautumėte idėjų, kaip tai padaryti!

5 žingsnis: Paskelbkite ir išbandykite!

Mes baigėme! Jūsų React programėlė dabar bus automatiškai išversta kiekvieną kartą, kai pridėsite bet kokias eilutes į Translate komponentą. Atkreipkite dėmesį, kad naujų verčiamų eilučių kūrimas bus įmanomas tik aplinkose, turinčiose API rakto read/write teises. Rekomenduojame turėti uždarą ir saugią testinę aplinką, kurioje galėtumėte išbandyti savo gamybinę programėlę su tokiu API raktu, pridėdami naujas eilutes prieš paleidžiant į veikiantį režimą. Tai apsaugos nuo jūsų slapto API rakto pavogimo ir galimo vertimų projekto išpūtimo pridėjus naujas, nesusijusias eilutes.

Būtinai peržiūrėkite visą pavyzdį mūsų GitHub profilyje. Ten taip pat rasite pavyzdį, kaip tai atlikti naudojant Pages Router systemą! Jei kiltų kokių nors problemų, nedvejodami kreipkitės, ir mes su malonumu jums padėsime.

TacoTranslate leidžia jums automatiškai lokalizuoti jūsų React programas greitai į bet kurią kalbą ir iš jos. Pradėkite šiandien!