Hvernig á að innleiða alþjóðavæðingu í Next.js-forriti sem notar App Router

Því sem heimurinn verður hnattvæddari verður það sífellt mikilvægara fyrir vefþróunaraðila að búa til forrit sem geta sinnt notendum frá ólíkum löndum og menningarheimum. Ein helsta leið til að ná þessu er alþjóðavæðing (i18n), sem gerir þér kleift að aðlaga forritið þitt að mismunandi tungumálum, gjaldmiðlum og dagsetningaformum.

Í þessari grein förum við yfir hvernig bæta má alþjóðavæðingu við React Next.js-forritið þitt með þjónsíðuframköllun. TL;DR: Sjáðu fulla dæmið hér.

Þessi leiðarvísir er fyrir Next.js forrit sem nota App Router.
Ef þú ert að nota Pages Router, sjá þennan leiðarvísir í staðinn.

Skref 1: Settu upp i18n-bókasafn

Til að innleiða alþjóðavæðingu í Next.js-forritið þitt munum við fyrst velja i18n-bókasafn. Það eru nokkur vinsæl bókasöfn, þar á meðal next-intl. Í þessu dæmi ætlum við hins vegar að nota TacoTranslate.

TacoTranslate þýðir sjálfkrafa textastrengi þína yfir á hvaða tungumál sem er með nýjustu gervigreind og frelsar þig frá leiðinlegri umsjón JSON-skrárinnar.

Setjum það upp með npm í skipanalínunni þinni:

npm install tacotranslate

Skref 2: Búðu til ókeypis TacoTranslate-reikning

Nú þegar þú hefur sett upp módúlinn er kominn tími til að stofna TacoTranslate-reikninginn þinn, þýðingarverkefni og tilheyrandi API-lykla. Stofnaðu reikning hér. Það er ókeypis og krefst ekki þess að þú gefir upp kreditkortsupplýsingar.

Búðu til verkefni í notendaviðmóti TacoTranslate og farðu í flipann fyrir API‑lykla. Búðu til einn read lykil og einn read/write lykil. Við munum vista þá sem umhverfisbreytur. read lykillinn er það sem við köllum public og read/write lykillinn er secret. Til dæmis gætir þú bætt þeim í .env skrá í rót verkefnisins.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gættu þess að leka aldrei hinum leynilega read/write API-lykli í framleiðsluumhverfi á viðskiptavinahlið.

Við munum einnig bæta við tveimur umhverfisbreytum: TACOTRANSLATE_DEFAULT_LOCALE og TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Sjálfgefinn varakóði fyrir svæðisstillingu. Í þessu dæmi setjum við hann á en fyrir ensku.
• TACOTRANSLATE_ORIGIN: “mappa” þar sem strengir þínir verða geymdir, til dæmis vefslóð vefsíðunnar þinnar. Lestu meira um origins hér.

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

Skref 3: Uppsetning TacoTranslate

Til að innleiða TacoTranslate í forritið þitt þarftu að búa til client sem notar API-lykla sem áður voru nefndir. Til dæmis, búðu til skrá sem heitir /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;

Við munum sjálfkrafa skilgreina TACOTRANSLATE_API_KEY og TACOTRANSLATE_PROJECT_LOCALE fljótlega.

Að búa til viðskiptavininn í sérstöku skrá gerir það auðvelt að nota hann aftur síðar. getLocales er einfaldlega hjálparfall með innbyggða villumeðhöndlun. Búðu nú til skrána /app/[locale]/tacotranslate.tsx, þar sem við munum útfæra TacoTranslate provider-inn.

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

Taktu eftir 'use client';, sem gefur til kynna að þetta sé hlutur á viðskiptavinahlið.

Nú þegar samhengisveitan er tilbúin skaltu búa til skrá sem heitir /app/[locale]/layout.tsx, rótarskipulagið í forritinu okkar. Athugaðu að þessi leið inniheldur möppu sem notar Dynamic Routes, þar sem [locale] er dýnamíska breytan.

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

Það sem vert er að hafa í huga er að við notum parameterinn Dynamic Route [locale] til að sækja þýðingar fyrir viðkomandi tungumál. Enn fremur tryggir generateStaticParams að allir staðarkóðar (locale codes) sem þú hefur virkjað fyrir verkefnið þitt séu fyrirfram renderaðir.

Nú skulum við búa til fyrstu síðu okkar! Búðu til skrá sem heitir /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!" />
	);
}

Taktu eftir breytunni revalidate sem segir Next.js að endurbyggja síðuna eftir 60 sekúndur og halda þýðingunum þínum uppfærðum.

Skref 4: Innleiðing renderunar á þjónsíðunni

TacoTranslate styður þjónsíðubirtingu. Þetta bætir notendaupplifunina til muna með því að sýna þýtt efni strax, í stað þess að notandinn sjái fyrst glampa af óþýddu efni. Enn fremur getum við sleppt netbeiðnum á klienthliðinni, því við höfum þegar þær þýðingar sem við þurfum fyrir síðuna sem notandinn er að skoða.

Til að setja upp server-side rendering skaltu búa til eða breyta /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};
};

Breyttu isProduction athuguninni svo hún passi við uppsetninguna þína. Ef true, mun TacoTranslate sýna opinbera API-lykilinn. Ef við erum í staðbundnu, prófunar- eða staging-umhverfi (isProduction is false), munum við nota leynda read/write API-lykilinn til að tryggja að nýir strengir séu sendir til þýðingar.

Til að tryggja að leiðsögn (routing) og endurvísun (redirection) virki eins og búist er við, þurfum við að búa til skrá sem heitir /middleware.ts. Með því að nota Middleware, getum við vísað notendum á síður sem birtast á þeirra valda tungumáli.

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

Gakktu úr skugga um að setja upp matcher í samræmi við Next.js Middleware skjöl.

Á viðskiptavinasíðunni geturðu breytt locale vafrakökunni til að breyta hvaða tungumál notandinn kýs. Sjáðu fulla dæmiskóðann fyrir hugmyndir um hvernig á að gera þetta!

Skref 5: Setja í dreifingu og prófa!

Það er búið! React-forritið þitt verður nú þýtt sjálfkrafa þegar þú bætir strengjum við Translate íhlut. Athugaðu að aðeins umhverfi sem hafa read/write heimildir fyrir API-lykil geta búið til nýja strengi til þýðingar. Við mælum með að þú hafir lokað og öruggt prófunarumhverfi þar sem þú getur prófað framleiðsluútgáfu forritsins með slíkum API-lykli og bætt við nýjum strengjum áður en farið er í loftið. Þetta mun koma í veg fyrir að einhver steli leyndum API-lyklinum þínum og hugsanlega fylla þýðingarverkefnið þitt með nýjum, ótengdum strengjum.

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!