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

Þegar heimurinn verður sífellt hnattvæddari er það æ mikilvægara fyrir vefþróunaraðila að byggja forrit sem geta mætt þörfum notenda úr ólíkum löndum og menningarheimum. Einn af helstu leiðum til að ná þessu er alþjóðavæðing (i18n), sem gerir þér kleift að laga forritið þitt að mismunandi tungumálum, gjaldmiðlum og dagsetningarformum.

Í þessari grein munum við kanna hvernig á að bæta alþjóðavæðingu við React Next.js-forritið þitt með server-side rendering. TL;DR: Sjáðu fulla dæmið hér.

Þessi leiðarvísir er fyrir Next.js-forrit sem nota App Router.
Ef þú notar Pages Router, sjáðu þessar leiðbeiningar í 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ð hins vegar nota TacoTranslate.

TacoTranslate þýðir strengina þína sjálfkrafa á hvaða tungumál sem er með hjálp háþróaðrar gervigreindar og losar þig undan leiðinlegri umsjón JSON-skráa.

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

npm install tacotranslate

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

Nú þegar þú hefur sett upp pakkann er komið að því að búa til TacoTranslate-reikninginn þinn, þýðingarverkefni og tilheyrandi API-lykla. Búðu til reikning hér. Það er ókeypis, og þú þarft ekki að bæta við kreditkorti.

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. Lykillinn read er það sem við köllum public og lykillinn read/write er secret. Til dæmis gætirðu bætt þeim við .env skrá í rót verkefnisins.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gakktu úr skugga um að leka aldrei hinum leynda read/write API-lykli til viðskiptavinshluta í framleiðsluumhverfum.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Sjálfgefinn varakóði fyrir staðbundna stillingu (locale). Í þessu dæmi munum við stilla hann á en fyrir ensku.
• TACOTRANSLATE_ORIGIN: „mappa“ þar sem strengirnir þínir verða geymdir, til dæmis vefslóð vefsíðunnar þinnar. Lestu nánar um origins hér.

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

Skref 3: Uppsetning TacoTranslate

Til að samþætta TacoTranslate við forritið þitt þarftu að búa til client með þeim API-lyklum sem þú bjóst til áðan. 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 fljótlega sjálfkrafa skilgreina TACOTRANSLATE_API_KEY og TACOTRANSLATE_PROJECT_LOCALE.

Að búa til client-inn í sérri skrá gerir það auðvelt að nota hann aftur síðar. getLocales er einfalt 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.

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

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 vert er að hafa í huga er að við notum Dynamic Route breytuna [locale] til að sækja þýðingar fyrir viðkomandi tungumál. Ennfremur sér generateStaticParams til þess að allir tungumálakóðar sem þú hefur virkjað í verkefninu þínu séu for-renderaðir.

Nú skulum við búa til 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 breytuna revalidate sem segir Next.js að endurbyggja síðuna eftir 60 sekúndur og halda þýðingum þínum uppfærðum.

Skref 4: Innleiðing server-side rendering

TacoTranslate styður birtingu á þjónsíðunni. Þetta bætir notendaupplifunina verulega með því að sýna þýtt efni strax, í stað þess að fyrst birtist tímabundið óþýtt efni. Að auki getum við sleppt netbeiðnum á viðskiptavinshliðinni, því við höfum þegar þær þýðingar sem við þurfum fyrir síðuna sem notandinn er að skoða.

Til að setja upp þjónustuhliðarrendrun, 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 athuguninni svo hún henti uppsetningu þinni. Ef true, mun TacoTranslate birta opinbera API-lykilinn. Ef við erum í staðbundnu, prófunar- eða staging-umhverfi (isProduction is false), munum við nota leynilega read/write API-lykilinn til að tryggja að nýir strengir séu sendir til þýðingar.

Til að tryggja að leiðakerfi og tilvísanir 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ð skjöl um Next.js Middleware.

Í viðskiptavinshlutanum geturðu breytt locale smákökunni til að breyta hvaða tungumál notandinn kýs. Vinsamlegast skoðaðu heildardæmi kóðans fyrir hugmyndir um hvernig á að gera þetta!

Skref 5: Setja í dreifingu og prófa!

Allt er klárt! React-forritið þitt verður nú sjálfkrafa þýtt þegar þú bætir hvaða strengi sem er í Translate íhlut. Athugaðu að aðeins umhverfi sem hafa read/write heimildir á API-lyklinum munu geta búið til nýja strengi til þýðingar. Við mælum með að hafa lokað og öruggt prófunarumhverfi (staging) þar sem þú getur prófað framleiðsluforritið þitt með slíkum API-lykli og bætt við nýjum strengjum áður en farið er í loftið. Þetta kemur í veg fyrir að einhver steli leynilega API-lykli þínum og mögulega fylli þýð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!