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

Kadangi pasaulis tampa vis labiau globalizuotas, vis svarbiau tampa interneto kūrėjams kurti programas, kurios galėtų patenkinti 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 su serverio pusės renderinimu. TL;DR: čia rasite pilną pavyzdį.

Šis vadovas skirtas Next.js programoms, kurios naudoja App Router.
Jei naudojate Pages Router, žr. šį 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 išverčia jūsų tekstus į bet kurią kalbą naudodamas pažangią DI technologiją ir atlaisvina jus nuo nuobodaus JSON failų valdymo.

Įdiekime jį naudodami npm savo terminale:

npm install tacotranslate

2 žingsnis: Sukurkite nemokamą TacoTranslate paskyrą

Dabar, kai turite įdiegtą modulį, laikas susikurti savo TacoTranslate paskyrą, vertimo projektą ir susijusius API raktus. Sukurkite paskyrą čia. Tai nemokama ir nereikalauja 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 tai, ką vadiname public, o read/write raktas yra secret. Pavyzdžiui, juos galite pridėti į .env failą savo projekto šakninėje direktorijoje.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Būkite tikri, kad niekada neišleisite slaptąjį read/write API raktą į kliento pusės gamybos aplinkas.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Numatytoji atsarginė lokalės kodas. Šiame pavyzdyje nustatysime jį kaip en - anglų kalba.
• TACOTRANSLATE_ORIGIN: „Aplankas“, kuriame bus saugomos jūsų frazės, pavyzdžiui, jūsų svetainės URL. Skaitykite daugiau apie origins č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 ankstesnius 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.

Kurti klientą atskirame faile leidžia jį lengvai naudoti vėliau. getLocales yra paprasta pagalbinė funkcija su įmontuotu klaidų valdymu. Dabar sukurkite failą pavadinimu /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>
	);
}

Pirmas dalykas, kurį čia reikia pažymėti, yra tai, kad mes naudojame mūsų Dynamic Route parametrą [locale] tam, kad gautume to kalbos vertimus. Be to, generateStaticParams užtikrina, kad visi lokalės kodai, kuriuos aktyvavote savo projekte, būtų iš anksto 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 perstatyti puslapį po 60 sekundžių ir palaikyti jūsų vertimus atnaujintais.

4 žingsnis: Serverio pusės atvaizdavimo įgyvendinimas

TacoTranslate palaiko serverio pusės atvaizdavimą. Tai žymiai pagerina naudotojo patirtį, rodant išverstą turinį iš karto, o ne pirmiausia rodyti neišverstą turinį trumpam. Be to, klientas gali praleisti tinklo užklausas, nes mes jau turime reikalingus vertimus puslapiui, kurį naudotojas ž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ų kaip numatyta, turėsime sukurti failą pavadinimu /middleware.ts. Naudodami Middleware galime peradresuoti vartotojus į jų pageidaujama kalba pateiktus 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 yra nustatytas pagal Next.js Middleware dokumentaciją.

Klientinėje pusėje galite pakeisti locale slapuką, kad pakeistumėte vartotojo pageidaujamą kalbą. Daugiau informacijos ir pavyzdžių rasite visoje pavyzdinėje kodo versijoje!

5 žingsnis: Diegti ir testuoti!

Mes baigėme! Jūsų React programa dabar bus automatiškai išversta, kai pridėsite bet kokius tekstus į Translate komponentą. Atkreipkite dėmesį, kad naujų tekstų kūrimui ir vertimui gali būti naudojamos tik tos aplinkos, kurios turi read/write teises prie API rakto. Rekomenduojame turėti uždarą ir apsaugotą vystymo aplinką, kurioje galėtumėte išbandyti savo gamybos programą su tokiu API raktu, pridėdami naujus tekstus prieš leidžiant ją į gyvą režimą. Tai apsaugos nuo jūsų slapto API rakto pavogimo ir potencialaus vertimo projekto užpildymo nereikalingais, nesusijusiais tekstais.

Būtinai peržiūrėkite pilną pavyzdį mūsų GitHub profilyje. Ten taip pat rasite pavyzdį, kaip tai padaryti naudojant Pages Router! Jei susidursite su kokiomis nors problemomis, drąsiai kreipkitės, mielai jums padėsime.

TacoTranslate leidžia automatiškai lokalizuoti jūsų React programas greitai ir bet kuria kalba. Pradėkite šiandien!