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

Því meira sem heimurinn verður hnattvæðari, því mikilvægara er fyrir vefhönnuði að búa til forrit sem geta mætt þörfum notenda frá mismunandi löndum og menningarheimum. Einn af lykilvegunum 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 dagsetningarsniðum.

Í þessari grein munum við kanna hvernig bæta má alþjóðavæðingu við React Next.js forritið þitt með þjónahliðar-renderun. TL;DR: Sjá 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áðu þá frekar þennan leiðarvísi.

Skref 1: Settu upp i18n bókasafn

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

TacoTranslate þýðir sjálfkrafa textastrengi þína á hvaða tungumál sem er með nýjustu gervigreind, og losar þig undan leiðinlegri stjórn á JSON skrám.

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 modulinn, er tími til að búa til TacoTranslate reikninginn þinn, þýðingarverkefni og tengda API lykla. Búðu til reikning hér. Það er ókeypis, og þarf ekki að bæta við kreditkorti.

Innan TacoTranslate forritsviðmótsins, búðu til verkefni og farðu í flipann fyrir API lyklana. 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 við .env skrá í rót verkefnisins þíns.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gakktu úr skugga um að leka aldrei leynilega read/write API lyklinum til client-side framleiðsluumhverfisins.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Sjálfgefið bakfalls tungumálakóði. Í þessu dæmi stillum við hann á en fyrir ensku.
• TACOTRANSLATE_ORIGIN: „Mappa“ þar sem textastrengir þínir verða geymdir, eins og slóð (URL) vefsíðu þ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 til þess að þetta sé client íhlutur.

Með samhengiþjóninum tilbúnum, búðu til skrá sem heitir /app/[locale]/layout.tsx, rótarskipulag í forritinu okkar. Athugaðu að þessi leið inniheldur möppu sem notar Dynamic Routes, þar sem [locale] er breytilegur breytuparameter.

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 ber að hafa í huga hér er að við notum Dynamic Route breytuna [locale] til að sækja þýðingar fyrir það tungumál. Að auki tryggir generateStaticParams að allar staðsetningarkóðar sem þú hefur virkjað fyrir verkefnið þitt séu forhannaðar.

Nú skulum við byggja okkar fyrsta síðu! 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ð endurgera síðuna eftir 60 sekúndur og halda þýðingunum þínum uppfærðum.

Skref 4: Innleiðing á þjónustuhliðarrennsli

TacoTranslate styður þjónustuhliðarröðun. Þetta bætir notendaupplifunina töluvert með því að sýna þýtt efni strax, í stað þess að sýna fyrst glampa af óþýddu efni. Auk þess getum við sleppt netbeiðnum á viðskiptavinahliðinni, því við höfum þegar þýðingarnar sem við þurfum fyrir síðuna sem notandinn er að skoða.

Til að setja upp miðlara-hliðarsíumyndun, búðu til eða breyttu /next.config.js skrá:

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 til að henta þinni uppsetningu. Ef true mun TacoTranslate sýna opinbera API lykilinn. Ef við erum í staðbundnu, prófunar- eða undirbúningsumhverfi (isProduction is false) munum við nota hinn dularfulla read/write API lykil til að ganga úr skugga um að nýjir strengir séu sendir til þýðingar.

Til að tryggja að leiðsla og umbeiting 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ð beina notendum á síður sem eru birtar á þ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 smákökunni til að skipta um 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 af stað og prófaðu!

Við erum búin! React forritið þitt verður nú sjálfvirkt þýtt þegar þú bætir við strengjum í Translate íhlutinn. Athugaðu að aðeins umhverfi með read/write réttindum á API lykli geta búið til nýja strengi til að þýða. Við mælum með að hafa lokað og öruggt prófunarumhverfi þar sem þú getur prófað framleiðsluappið þitt með slíkan API lykil, og bætt við nýjum strengjum áður en farið er í beinu útsendingu. Þetta kemur í veg fyrir að einhver steli leynilega API lyklinum þí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!