Kaip įgyvendinti lokalizaciją Next.js programėlėje, kuri naudoja App Router

Kadangi pasaulis tampa vis labiau globalizuotas, vis svarbiau interneto kūrėjams kurti programas, kurios galėtų aptarnauti vartotojus iš skirtingų šalių ir kultūrų. Vienas pagrindinių būdų tai pasiekti yra tarptautinimas (i18n), leidžiantis pritaikyti jūsų programą skirtingoms kalboms, valiutoms ir datų formatams.

Šiame straipsnyje išnagrinėsime, kaip pridėti tarptautinimą jūsų React Next.js programai su serverio pusės atvaizdavimu. TL;DR: Čia rasite pilną pavyzdį.

Ši instrukcija skirta Next.js programoms, naudojančioms App Router.
Jei naudojate Pages Router, vietoje to peržiūrėkite šią instrukciją.

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ų tekstus į bet kurią kalbą naudodamas pažangiausią dirbtinį intelektą ir atlaisvina jus nuo nuobodaus JSON failų valdymo.

Įdiekime jį naudodami npm jūsų terminale:

npm install tacotranslate

2 žingsnis: Sukurkite nemokamą TacoTranslate paskyrą

Dabar, kai įdiegėte modulį, laikas sukurti savo TacoTranslate paskyrą, vertimo projektą ir susijusius API raktus. Sukurkite paskyrą čia. Tai nemokama ir nereikalauja pridėti kreditinės 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 raktą mes vadiname public, o read/write raktą – secret. Pavyzdžiui, juos galite pridėti į .env failą savo projekto šakniniame kataloge.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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 nustatysime ją kaip en anglų kalbai.
• TACOTRANSLATE_ORIGIN: „Aplankas“, kuriame bus saugomos jūsų eilutės, pavyzdžiui, jūsų svetainės URL. Skaitykite daugiau apie šaltinius č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 tiesiog 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 klientinė komponentė.

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 pažymėti, yra tai, kad naudojame mūsų Dynamic Route parametrą [locale] norėdami gauti vertimus tam konkrečiam kalbos kodui. Be to, generateStaticParams užtikrina, kad visi jūsų projekte aktyvuoti kalbos 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 perstatyti puslapį po 60 sekundžių ir palaikyti jūsų vertimus atnaujintus.

4 žingsnis: Serverio pusės atvaizdavimo įgyvendinimas

TacoTranslate palaiko serverio pusės renderinimą. Tai žymiai pagerina vartotojo patirtį, nes iš karto rodomas išverstas turinys, o ne pirmiausia trumpas nevertinto turinio mirksnis. Be to, galime praleisti tinklo užklausas kliento pusėje, nes jau turime reikalingus vertimus 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ų 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 tinkamą maršrutizavimą ir nukreipimą, turėsime sukurti failą pavadinimu /middleware.ts. Naudodami Middleware, galime nukreipti vartotojus į puslapius 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 sukonfigūruotas pagal Next.js Middleware dokumentaciją.

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

5 žingsnis: Diegti ir testuoti!

Mes baigėme! Jūsų React programa dabar bus automatiškai išversta, kai pridėsite bet kokias eilutes į Translate komponentą. Atkreipkite dėmesį, kad naujas eilutes galės kurti tik tie aplinkos nustatymai, kurie turi read/write teisės API raktui. Rekomenduojame turėti uždarą ir saugią testavimo aplinką, kur galite išbandyti savo gamybinę programą su tokio tipo API raktu, pridėdami naujas eilutes prieš paleidžiant gyvai. Tai apsaugos nuo to, kad kas nors pavogtų jūsų slapto API rakto, ir neprisidarys nereikalingų bei nesusijusių eilučių, kurios galėtų užkrauti jūsų vertimų projektą.

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 susisiekite, ir mes mielai jums padėsime.

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