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

Namate die wêreld meer gevestig raak, word dit al hoe belangriker vir webontwikkelaars om toepassings te bou wat vir gebruikers uit verskillende lande en kulture kan voorsien. Een van die sleutels tot die bereiking hiervan is internasionaalsisering (i18n), wat jou toelaat om jou toepassing aan te pas by verskillende tale, geldeenhede en datumsformate.

In hierdie artikel gaan ons ondersoek instel na hoe om internasionaalsisering by jou React Next.js-toepassing te voeg, met bediener-kant weergawes. 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 eerder hierdie gids.

Stap 1: Installeer 'n i18n-biblioteek

Om internasionale ondersteuning in jou Next.js-toepassing te implementeer, gaan ons eers ’n i18n-biblioteek kies. Daar is verskeie populêre biblioteke, insluitend next-intl. In hierdie voorbeeld gaan ons egter TacoTranslate gebruik.

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

Laat ons dit installeer met npm in jou terminal:

npm install tacotranslate

Stap 2: Skep 'n gratis TacoTranslate-rekening

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

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Maak seker dat jy die geheime read/write API-sleutel nooit na kliëntkant produksie-omgewings lek nie.

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

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

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

Stap 3: Opstel van TacoTranslate

Om TacoTranslate met jou toepassing te integreer, moet jy ’n kliënt skep met die API-sleutels van vroeër. Skep byvoorbeeld ’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 gaan binnekort automatisch TACOTRANSLATE_API_KEY en TACOTRANSLATE_PROJECT_LOCALE definieer.

Om die kliënt in ’n aparte lêer te skep maak dit maklik om dit later weer te gebruik. getLocales is net ’n hulpmiddel-funksie met ingeboude foutbehandeling. Skep nou ’n lêer met die naam /app/[locale]/tacotranslate.tsx, waar ons die TacoTranslate verskaffer gaan 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 die 'use client'; wat aandui dat dit ’n kliëntkomponent is.

Met die konteksverskaffer nou gereed, skep ʼn lêer genaamd /app/[locale]/layout.tsx, die wortel-uitleg in ons toepassing. Neem kennis dat hierdie pad ʼn gids het 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 ons Dynamic Route parameter [locale] gebruik om vertalings vir daardie taal te bekom. Daarbenewens sorg generateStaticParams dat al die locale-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 Next.js vertel om die bladsy na 60 sekondes weer op te bou, en jou vertalings op datum te hou.

Stap 4: Die implementering van bediener-kant rendering

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

Om bediener-side 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};
};

Pas die isProduction kontrole aan om by jou opstelling te pas. As dit true is, 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 nuwe stringe word vir vertaling gestuur.

Om te verseker dat roetering en herleiding soos verwag werk, sal ons ʼn lêer met die naam /middleware.ts moet skep. Deur gebruik te maak van Middleware, 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 dat jy die matcher opstel in ooreenstemming met die Next.js Middleware dokumentasie.

Aan die kliënt-kant kan jy die locale koekie verander om te wys wat die gebruiker se voorkeurtaal is. 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 automatisch vertaal word wanneer jy enige stringe by 'n Translate komponent voeg. Let daarop dat slegs omgewings met read/write toestemmings op die API-sleutel nuwe stringe kan skep wat vertaal moet word. Ons beveel aan om 'n geslote en veilige staging-omgewing te hê waar jy jou produksie-toepassing met so 'n API-sleutel kan toets, en nuwe stringe kan byvoeg voordat dit regstreeks gaan. Dit sal verhoed dat iemand jou geheime API-sleutel steel, en moontlik jou vertaalprojek oorlaai 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!