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

Þar sem heimurinn verður sífellt hnattvæddari er það æ mikilvægara fyrir vefhönnuði að byggja forrit sem geta þjónustað notendur frá mismunandi löndum og menningarheimum. Ein af lykilleiðunum til að ná þessu markmiði er með alþjóðavæðingu (i18n), sem gerir þér kleift að aðlaga forritið þitt að mismunandi tungumálum, gjaldmiðlum og dagsetningasniðum.

Í þessum grein munum við kanna hvernig bæta má alþjóðavæðingu við React Next.js forritið þitt, með þjónustu á netþjóni. 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, skoðaðu þá frekar þennan leiðarvísi.

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 til 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 strengina þína yfir á hvaða tungumál sem er með nýjustu gervigreind og losar þig frá leiðinlegri meðhöndlun JSON-skráa.

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

npm install tacotranslate

Skref 2: Búðu til ókeypis TacoTranslate aðgang

Nú þegar þú hefur sett upp viðbótina er kominn tími til að búa til TacoTranslate reikninginn þinn, þýðingarverkefni og tengda API lykla. Búðu til reikning hér. Þetta er ókeypis, og krefst ekki kreditkortaupplýsinga.

Innan TacoTranslate forritaviðmótsins, búðu til verkefni og farðu á flipa fyrir API-lyklana. Búðu til einn read lykil og einn read/write lykil. Við munum vista þá sem umhverfisbreytur. read lykillinn kallast public og read/write lykillinn er secret. Til dæmis gætir þú 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 leynilegum read/write API lykli til framleiðsluumhverfa á viðmóti hliðar viðskiptavinar.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Sjálfgefið varafall staðsetningarkóða. Í þessu dæmi setjum við það á en fyrir enska.
• TACOTRANSLATE_ORIGIN: „Mappa“ þar sem strengirnir þínir verða geymdir, eins og slóð 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ð samþætta TacoTranslate við forritið þitt þarftu að búa til client með því að nota API lykla sem fengnir voru fyrr. 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ér skrá gerir það auðvelt að nota aftur seinna. getLocales er einfaldlega hjálparfall með innbyggðum villumeðhöndlun. Nú skaltu búa 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 bendir á að þetta sé client íhlutur.

Með samhengisveituna tilbúna, búðu til skrá sem heitir /app/[locale]/layout.tsx, rótarlayout í forritinu okkar. Athugaðu að þessi staðsetning inniheldur möppu sem notar Dynamic Routes, þar sem [locale] er breytilegur breytuvalkostur.

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 þarf að taka eftir hér er að við erum að nota okkar Dynamic Route breytu [locale] til að sækja þýðingar fyrir það tungumál. Að auki tryggir generateStaticParams að öll tungumálakóðarnir sem þú hefur virkjað fyrir verkefnið þitt eru forhannað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!" />
	);
}

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

Skref 4: Innleiðing á server-side rendering

TacoTranslate styður við server side rendering. Þetta bætir notendaupplifunina verulega með því að sýna þýtt efni strax, í stað þess að birta fyrst ósagða efni sem skammvinnan glampi. Að auki getum við sleppt netbeiðnum á viðskiptavinahliðinni, því við höfum þegar þýðingarnar sem við þurfum fyrir síðuna sem notandinn skoðar.

Til að stilla miðlungsþjónshluta 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 skilyrðinu til að henta þinni uppsetningu. Ef true er, mun TacoTranslate sýna almenna API lykilinn. Ef við erum í staðbundnu, prófunar- eða uppsetningarumhverfi (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ðbeiningar og umbeining virki eins og ætlast er til, þ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 uppáhaldssmá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ðu breytt locale kökunni til að breyta hvaða tungumál notandinn kýs. Vinsamlegast skoðaðu fullkomna dæmakóðann fyrir hugmyndir um hvernig á að gera þetta!

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

Við erum búin! React forritið þitt verður nú sjálfkrafa þýtt þegar þú bætir við strengjum í Translate íhlutinn. Athugaðu að aðeins umhverfi með read/write réttindi á API lykli munu geta búið til nýja strengi til þýðingar. Við mælum með að hafa lokað og öruggt staging-umhverfi þar sem þú getur prófað framleiðsluforritið þitt með slíkan API lykil, bætt við nýjum strengjum áður en þú setur það í loftið. Þetta kemur í veg fyrir að einhver steli leynilega API lykli þínum og mögulega stækki þýð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!