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

Þegar heimurinn verður sífellt hnattvæðari er það æ mikilvægara fyrir vefhönnuði að byggja forrit sem geta mætt þörfum notenda frá mismunandi löndum og menningarheimum. Eitt af helstu leiðunum 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 dagsetningasniðum.

Í þessari grein munum við skoða hvernig bæta má alþjóðavæðingu við React Next.js-forritið þitt með renderingu á þjónustuhlið. TL;DR: Sjá dæmið í heild hér.

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

Skref 1: Settu upp i18n-bókasafn

Til að innleiða alþjóðavæðingu í Next.js-forritinu þínu skulum 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 sjálfkrafa strengina þína á öll tungumál með hjálp háþróaðrar gervigreindar og losar þig frá leiðinlegri umsjón með JSON-skrám.

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

npm install tacotranslate

Skref 2: Stofnaðu ókeypis TacoTranslate-reikning

Nú þegar þú hefur sett upp módúlinn er komið að því að búa til TacoTranslate-reikninginn þinn, þýðingarverkefni og viðeigandi API-lykla. Skráðu þig hér. Það er ókeypis og þú þarft ekki að bæta við kreditkorti.

Í notendaviðmóti TacoTranslate-forritsins, búðu til verkefni og farðu í flipann fyrir API-lykla þess. 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 leynilega read/write API-lykli í framleiðsluumhverfi á viðskiptavinahliðinni.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Sjálfgefinn varakóði fyrir tungumál. Í þessu dæmi stillum við hann á en fyrir ensku.
• TACOTRANSLATE_ORIGIN: „mappa“ þar sem textastrengirnir þínir verða geymdir, til dæmis vefslóð vefsíðunnar þinnar. Lestu meira um uppruna 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 viðskiptavin með API-lyklunum frá áð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 sjálfkrafa skilgreina TACOTRANSLATE_API_KEY og TACOTRANSLATE_PROJECT_LOCALE innan skamms.

Að búa til client í 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 veituna.

'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 bendir til þess að þetta sé viðskiptavinahluti.

Með samhengi-veitunni núna tilbúnni, búðu til skrá sem heitir /app/[locale]/layout.tsx, 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>
	);
}

Það fyrsta sem vert er að taka fram hér er að við notum Dynamic Route breytuna [locale] til að sækja þýðingar fyrir það tungumál. Auk þess tryggir generateStaticParams að allir tungumálakóðar sem þú hefur virkjað fyrir verkefnið þitt séu renderaðir fyrirfram.

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!" />
	);
}

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 þjónsíðubirtingar

TacoTranslate styður rendering á þjónustuhlið. Þetta bætir notendaupplifun verulega með því að sýna þýtt efni strax, í stað þess að fyrst sjái notandinn glampa af óþýddu efni. Ennfremur getum við sleppt netbeiðnum í vafranum, því við höfum þegar þær þýðingar sem þarf fyrir síðuna sem notandinn er að skoða.

Til að setja upp þjónshliðarrendering 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 birta opinbera API-lykilinn. Ef við erum í staðbundnu, prófunar- eða staging-umhverfi (isProduction is false), munum við nota leynilegan read/write API-lykilinn til að ganga úr skugga um 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ð setja upp matcher í samræmi við Next.js Middleware-skjölin.

Á client-hliðinni getur þú breytt smákökunni locale til að stilla hvaða tungumál notandinn kýs. Sjáðu heildarkóðann fyrir dæmið til að fá hugmyndir um hvernig á að gera þetta!

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

Allt klárt! React-forritið þitt verður nú sjálfkrafa þýtt þegar þú bætir við einhverjum strengjum í Translate íhlut. Athugaðu að aðeins umhverfi með read/write heimildir fyrir API-lykilinn geta búið til nýja strengi til þýðingar. Við mælum með að hafa lokað og öruggt prófanarumhverfi þar sem þú getur prófað framleiðsluútgáfu forritsins með slíkum API-lykli og bætt við nýjum strengjum áður en það fer í framleiðslu. Þetta mun koma í veg fyrir að einhver einhver steli leynilegum API-lykli þínum og mögulega ofhlaði þýð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!