Hoe om internasionalisering in 'n Next.js-toepassing te implementeer wat die App Router gebruik

Soos die wêreld meer geglobaliseer raak, is dit toenemend belangrik vir webontwikkelaars om toepassings te bou wat gebruikers uit verskillende lande en kulture kan akkommodeer. Een van die sleutelmaniere om dit te bereik is deur internasionalisering (i18n), wat jou in staat stel om jou toepassing aan verskillende tale, geldeenhede en datumformate aan te pas.

In hierdie artikel gaan ons ondersoek hoe om internasionalisering by jou React Next.js-toepassing te voeg, met bedienerkant-rendering. TL;DR: Sien die volledige voorbeeld hier.

Hierdie gids is vir Next.js-toepassings wat die App Router gebruik.
As jy die Pages Router gebruik, sien hierdie gids in plaas daarvan.

Stap 1: Installeer 'n i18n-biblioteek

Om internasionalsiering in jou Next.js-toepassing te implementeer, kies ons eers 'n i18n-biblioteek. Daar is verskeie gewilde biblioteke, insluitende next-intl. In hierdie voorbeeld gaan ons egter TacoTranslate.

TacoTranslate vertaal jou stringe outomaties na enige taal met behulp van gevorderde KI, en verlos jou van die vervelige bestuur van JSON-lêers.

Kom ons installeer dit met behulp van npm in jou terminal:

npm install tacotranslate

Stap 2: Maak 'n gratis TacoTranslate-rekening aan

Nou dat jy die module geïnstalleer het, is dit tyd om jou TacoTranslate-rekening, 'n vertaalprojek en die gekoppelde API-sleutels te skep. Skep hier 'n rekening. Dit is gratis, en dit vereis nie dat jy 'n kredietkaart byvoeg nie.

Binne die TacoTranslate-toepassing se gebruikerskoppelvlak, skep 'n projek en navigeer na die API-sleutels-oortjie daarvan. Skep een read sleutel en een read/write sleutel. Ons sal hulle as omgewingsveranderlikes stoor. Die read sleutel is wat ons public noem en die read/write sleutel is secret. Byvoorbeeld, jy kan hulle byvoeg in 'n .env lêer in die wortel van jou projek.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Maak seker dat die geheime read/write API-sleutel nooit aan kliëntkant-produksie-omgewings gelek word nie.

Ons sal ook nog twee omgewingsveranderlikes byvoeg: TACOTRANSLATE_DEFAULT_LOCALE en TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Die standaard terugval-lokaalkode. In hierdie voorbeeld stel ons dit op en vir Engels.
• TACOTRANSLATE_ORIGIN: Die “map” waar jou stringe gestoor sal word, soos die URL van jou webwerf. Lees hier meer oor oorspronge.

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

Stap 3: TacoTranslate instel

Om TacoTranslate in jou toepassing te integreer, moet jy 'n kliënt skep met behulp van die API-sleutels van vroeër. Byvoorbeeld, skep 'n lêer met die naam /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;

Ons sal binnekort die TACOTRANSLATE_API_KEY en TACOTRANSLATE_PROJECT_LOCALE outomaties definieer.

Om die kliënt in 'n aparte lêer te plaas, maak dit maklik om dit later weer te gebruik. getLocales is net 'n nutsfunksie met 'n paar ingeboude foutbehandeling. Skep nou 'n lêer genaamd /app/[locale]/tacotranslate.tsx, waar ons die TacoTranslate aanbieder sal implementeer.

'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>
	);
}

Let op die 'use client'; wat aandui dat dit 'n kliëntkomponent is.

Met die konteksverskaffer nou gereed om te gebruik, skep 'n lêer met die naam /app/[locale]/layout.tsx, die root-layout van ons toepassing. Let daarop dat hierdie pad 'n gids bevat wat gebruik maak van Dynamic Routes, waar [locale] die dinamiese parameter is.

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>
	);
}

Die eerste ding om hier op te let is dat ons die Dynamic Route parameter [locale] gebruik om vertalings vir daardie taal te haal. Daarbenewens verseker generateStaticParams dat al die lokalisasie-kodes wat jy vir jou projek geaktiveer het, vooraf gerender word.

Kom ons bou nou ons eerste bladsy! Skep 'n lêer met die naam /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!" />
	);
}

Let op die revalidate veranderlike wat vir Next.js sê om die bladsy na 60 sekondes weer te bou, en jou vertalings op datum te hou.

Stap 4: Implementering van bedienerkant-weergawing

TacoTranslate ondersteun bedienerkant-weergawing. Dit verbeter die gebruikerservaring aansienlik deur vertaalde inhoud onmiddellik te vertoon, in plaas van eers ’n flits van onvertaalde inhoud. Daarbenewens kan ons netwerkversoeke op die kliënt oorslaan, omdat ons reeds die vertalings het wat benodig word vir die bladsy wat die gebruiker besigtig.

Om bedienerkant-rendering op te stel, skep of wysig /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};
};

Verander die isProduction kontrole sodat dit by jou opstelling pas. As true, sal TacoTranslate die publieke API-sleutel openbaar maak. As ons in 'n plaaslike, toets- of staging-omgewing is (isProduction is false), sal ons die geheime read/write API-sleutel gebruik om seker te maak dat nuwe stringe vir vertaling gestuur word.

Om te verseker dat routering en herleiding soos verwag werk, moet ons 'n lêer met die naam /middleware.ts skep. Deur Middleware te gebruik, kan ons gebruikers herlei na bladsye wat in hul voorkeurtaal aangebied word.

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);
}

Maak seker om die matcher op te stel ooreenkomstig die Next.js Middleware-dokumentasie.

Aan die kliëntkant kan jy die locale koekie verander om die gebruiker se voorkeurtaal te verander. Sien asseblief die volledige voorbeeldkode vir idees oor hoe om dit te doen!

Stap 5: Ontplooi en toets!

Ons is klaar! Jou React-toepassing sal nou outomaties vertaal word wanneer jy enige stringe aan 'n Translate komponent toevoeg. Neem asseblief kennis dat slegs omgewings met read/write toestemmings op die API-sleutel nuwe stringe sal kan skep wat vertaal moet word. Ons beveel aan om 'n geslote en beveiligde staging-omgewing te hê waar jy jou produksietoepassing met so 'n API-sleutel kan toets en nuwe stringe kan byvoeg voordat dit in produksie gaan. Dit sal verhoed dat enigiemand enigiemand jou geheime API-sleutel steel, en moontlik jou vertaalprojek laat aanswel deur nuwe, nie-verwante stringe by te voeg.

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!