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

Namate die wêreld meer geglobaliseer raak, word dit al hoe belangriker vir webontwikkelaars om toepassings te bou wat gebruikers van verskillende lande en kulture kan bedien. Een van die sleutelweë om dit te bereik, is deur internasionale aanpassing (i18n), wat jou toelaat om jou toepassing aan te pas vir verskillende tale, geldeenhede en datumformate.

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

Hierdie gids is vir Next.js-toepassings wat die App Router gebruik.
As u die Pages Router gebruik, sien eerder hierdie gids.

Stap 1: Installeer ’n i18n-biblioteek

Om internasionaleisering in jou Next.js-toepassing te implementeer, sal ons eers ’n i18n-biblioteek kies. Daar is verskeie gewilde biblioteke, insluitend next-intl. In hierdie voorbeeld gaan ons egter gebruik maak van TacoTranslate.

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 behulp van npm in jou terminal:

npm install tacotranslate

Stap 2: Skep 'n gratis TacoTranslate-rekening

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

Binne die TacoTranslate toepassing UI, skep 'n projek, en navigeer na die API-sleutels-oortjie daarvan. Skep een read sleutel, en een read/write sleutel. Ons sal dit as omgewingveranderlikes stoor. Die read sleutel is wat ons public noem en die read/write sleutel is secret. Byvoorbeeld, jy kan dit 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 jy nooit die geheime read/write API-sleutel 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-lokale-kode. In hierdie voorbeeld stel ons dit op en vir Engels.
• TACOTRANSLATE_ORIGIN: Die “lêer” waar jou snare 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: Die opstel van TacoTranslate

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;

Ons sal binnekort outomaties TACOTRANSLATE_API_KEY en TACOTRANSLATE_PROJECT_LOCALE definieer.

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

Met die konteksverskaffer wat nou gereed is om te gaan, skep 'n lêer met die naam /app/[locale]/layout.tsx, die worteluitleg in ons toepassing. Let daarop dat hierdie pad 'n gids het wat Dynamic Routesgebruik, 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 kry. Daarbenewens sorg generateStaticParams daarvoor dat al die lokale kode wat jy vir jou projek geaktiveer het, voorafvertoon 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 wel 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 bediener-kant rendering

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

Om bediener-kant 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 om by jou opstelling te pas. As dit true is, sal TacoTranslate die openbare 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 routering 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 ooreenkomstig die Next.js Middleware-dokumentasie.

Aan die kliëntkant kan jy die locale koekie verander om die gebruiker se voorkeurtaal aan te pas. 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 by ʼn Translate komponent voeg. Neem kennis dat slegs omgewings met read/write regte op die API-sleutel nuwe stringe kan skep om vertaal te 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 jy dit regstreekse maak. Dit sal voorkom dat iemand jou geheime API-sleutel steel en moontlik jou vertaalprojek opblaas deur nuwe, nie-verwante stringe by te voeg.

Maak seker dat jy die volledige voorbeeld by ons GitHub-profiel nagaan. Daar sal jy ook 'n voorbeeld vind van hoe om dit te doen met die Pages Router! As jy enige probleme ondervind, voel vry om kontak te maak, en ons sal meer as bly wees om te help.

TacoTranslate stel jou in staat om jou React-toepassings outomaties vinnig te lokaliseer na en van enige taal af. Begin vandag!