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

Á meðan heimurinn verður sífellt alþjóðlegri, er það æ mikilvægara fyrir vefur þróunaraðila að búa til forrit sem geta mætt þörfum notenda frá mismunandi löndum og menningarheimum. Ein af lykilleiðunum til að ná þessu er í gegnum alþjóðavæðingu (i18n), sem gerir þér kleift að aðlaga forritið þitt að mismunandi tungumálum, gjaldmiðlum og dagsetningarsniðum.

Í þessari grein munum við kanna hvernig á að bæta alþjóðavæðingu við React Next.js forritið þitt, með þjónustuhliðarröðun. TL;DR: Sjáðu dæmið í heild hér.

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

Skref 1: Settu upp i18n bókasafn

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

TacoTranslate þýðir sjálfkrafa strengina þína á hvaða tungumál sem er með nýjustu gervigreind, og losar þig undan þreytandi umsýslu JSON skrár.

Við skulum setja það upp með npm í skipanalínunni þinni:

npm install tacotranslate

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

Nú þegar þú hefur sett upp móðulinn er kominn tími til að búa til TacoTranslate reikninginn þinn, þýðingarverkefni og tengd API lykla. Búðu til reikning hér. Það er ókeypis og krefst ekki þess að þú setjir inn kreditkort.

Innan TacoTranslate forritsins skaltu búa til verkefni og fara í API lykla flipann. 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ðu bætt þeim við .env skrá í rót verkefnisins þíns.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gakktu úr skugga um að leka aldrei leynilegu read/write API lyklinum í framleiðsluumhverfi á viðskiptavinahlið.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Viðmiðunar sjálfgefinn staðarkóði. Í þessu dæmi stillum við hann á en fyrir ensku.
• TACOTRANSLATE_ORIGIN: „Möppan“ þar sem strengir þínir verða vistaðir, eins og slóð vefsíðunnar þinnar. Lestu meira um origins hér.

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

Skref 3: Að setja upp TacoTranslate

Til að samþætta TacoTranslate við forritið þitt þarftu að búa til client sem notar API-lykla sem þú bjóst til áðan. Til dæmis, búðu til skrána /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 innan skamms.

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á sem heitir /app/[locale]/tacotranslate.tsx, þar sem við munum útfæra TacoTranslate veitandann.

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

Athugaðu 'use client'; sem gefur til kynna að þetta sé client-íhlutur.

Með samhengi veitanum (context provider) nú tilbúinn, búðu til skrá sem heitir /app/[locale]/layout.tsx, rótarklippuna (root layout) í forritinu okkar. Athugaðu að þetta slóð hefur möppu sem notar Dynamic Routes, þar sem [locale] er breytilegur (dynamískur) þáttur.

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

Fyrsta sem þarf að taka eftir hér er að við notum Dynamic Route breytuna okkar [locale] til að sækja þýðingar fyrir það tungumál. Að auki sér generateStaticParams fyrir því að allir staðbundnu kóðar sem þú hefur virkjað fyrir verkefnið þitt séu forsniðnir.

Nú skulum við byggja fyrstu síðuna 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!" />
	);
}

Athugaðu revalidate breytuna sem segir Next.js að byggja síðuna upp aftur eftir 60 sekúndur og halda þýðingunum þínum uppfærðum.

Skref 4: Innleiðing þjónustuhliðarútgáfu

TacoTranslate styður við miðlara-renderun (server side rendering). Þetta bætir notendaupplifunina verulega með því að sýna þýtt efni strax, í stað þess að sýna óþýtt efni um stund fyrst. Að auki getum við sleppt netbeiðnum á viðskiptavinssíðunni, þar sem við höfum þegar þýðingarnar sem við þurfum fyrir síðuna sem notandinn er að skoða.

Til að setja upp server side rendering, búðu til eða breyttu /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 prófinu svo það henti þinni uppsetningu. Ef true, mun TacoTranslate sýna opinbera API lykilinn. Ef við erum í staðbundnu, prófunar- eða gagnsögusvæði (isProduction is false), munum við nota leynilega read/write API lykilinn til að tryggja að nýjar strengjar séu sendir til þýðingar.

Til að tryggja að leiðsögn og tilvísun 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 eru sýndar á þ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ð stilla matcher í samræmi við Next.js Middleware skjölun.

Á viðskiptavinahliðinni getur þú breytt locale kökunni til að breyta því hvaða tungumál notandinn kýs sér. Vinsamlegast sjáðu fullkomna dæmakóðann fyrir hugmyndir um hvernig á að gera þetta!

Skref 5: Settu í framleiðslu og prófaðu!

Við erum búin! React forritið þitt mun nú sjálfkrafa vera þýtt þegar þú bætir við strengjum í Translate íhlutinn. Athugaðu að aðeins umhverfi með read/write heimildir á API lykli geta búið til nýja strengi sem á að þýða. Við mælum með að hafa lokað og öruggt prófunarumhverfi þar sem þú getur prófað framleiðsluútgáfu forritsins með API lykli eins og þessum, og bætt við nýjum strengjum áður en þú ferð í loftið. Þetta mun koma í veg fyrir að einhver stæði upp með leynilegan API lykil þinn og mögulega stækkaði þýðingarverkefnið þitt með því að bæta við 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!