Ինչպես իրականացնել բազմալեզվայնություն Next.js հավելվածում, որը օգտագործում է App Router

Աշխարհի գլոբալացման հետ մեկտեղ վեբ ծրագրավորողների համար առավել կարևոր է ստեղծել այնպիսի հավելվածներ, որոնք կարող են բավարարել տարբեր երկրների և մշակույթների օգտատերերի կարիքները։ Մեկը հիմնական ուղիներից դրա հասնելու համար միջազգայինացումն է (i18n), որը թույլ է տալիս հարմարեցնել ձեր հավելվածը տարբեր լեզուների, արժույթների և ամսաթվի ձևաչափերի համար։

Այս հոդվածում մենք կքննարկենք, թե ինչպես ավելացնել միջազգայինացում ձեր React Next.js հավելվածում՝ սերվերային կողմի ռենդերավորմամբ։ TL;DR: Լրիվ օրինակն այստեղ։

Այս ուղեցույցը նախատեսված է Next.js հավելվածների համար, որոնք օգտագործում են App Router.
Եթե դուք օգտագործում եք Pages Router, դրա փոխարեն տեսեք այս ուղեցույցը.

Քայլ 1՝ Տեղադրեք i18n գրադարան

Ձեր Next.js հավելվածում բազմալեզվայնություն (i18n) իրականացնելու համար մենք սկզբից կընտրենք i18n գրադարան։ Կան մի քանի հանրաճանաչ գրադարաններ, ներառյալ next-intl. Այս օրինակով, սակայն, մենք կօգտագործենք TacoTranslate.

TacoTranslate-ը ավտոմատ կերպով ձեր տողերը թարգմանում է ցանկացած լեզվով՝ օգտագործելով առաջադեմ արհեստական բանականություն, և ազատում է ձեզ JSON ֆայլերի հոգնեցուցիչ կառավարման աշխատանքից։

Տեղադրենք այն՝ օգտագործելով npm ձեր տերմինալում։

npm install tacotranslate

Քայլ 2: Ստեղծեք անվճար TacoTranslate-ի հաշիվ

Հիմա, երբ մոդուլը տեղադրված է, ժամանակն է ստեղծել ձեր TacoTranslate հաշվը, թարգմանական նախագիծը և համապատասխան API բանալիները։ Ստեղծեք հաշիվ այստեղ։ Դա անվճար է, և չպահանջում է վարկային քարտի տվյալներ։

TacoTranslate հավելվածի UI-ում ստեղծեք նախագիծ և անցեք նրա API բանալիների ներդիրին։ Ստեղծեք մեկ read բանալին և մեկ read/write բանալին։ Մենք դրանք կպահպանենք շրջակա միջավայրի փոփոխականների մեջ։ read բանալին կոչվում է public, իսկ read/write բանալին՝ secret։ Օրինակ՝ կարող եք դրանք ավելացնել ձեր նախագծի արմատում գտնվող .env ֆայլում։

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Համոզվեք, որ երբեք չբացահայտեք գաղտնի read/write API բանալին կլիենտի կողմի արտադրական միջավայրերին։

Մենք նաև կավելացնենք ևս երկու միջավայրային փոփոխական՝ TACOTRANSLATE_DEFAULT_LOCALE և TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Սա կանխորոշված հետընտրող (fallback) տեղայնացման կոդն է։ Այս օրինակով մենք այն կկարգենք որպես en՝ անգլերենի համար։
• TACOTRANSLATE_ORIGIN: «Պանակը», որտեղ կհամբարվեն ձեր տեքստերը, օրինակ՝ ձեր կայքի URL-ը։ Ավելին՝ origins-ների մասին կարդացեք այստեղ։

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

Քայլ 3: TacoTranslate-ի կարգավորումը

TacoTranslate-ը ձեր հավելվածին ինտեգրելու համար պետք է ստեղծեք մի հաճախորդ՝ օգտագործելով ավելի վաղ ստեղծված API բանալիները։ Օրինակ՝ ստեղծեք ֆայլ՝ /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;

Մենք շուտով ավտոմատ կերպով կսահմանենք TACOTRANSLATE_API_KEY և TACOTRANSLATE_PROJECT_LOCALE.

Հաճախորդի ստեղծումը առանձին ֆայլում հեշտացնում է այն հետագայում կրկին օգտագործելը։ getLocales ընդամենը օգտակար ֆունկցիա է, որը ունի որոշ ներքին սխալների մշակման մեխանիզմ։ Այժմ ստեղծեք ֆայլ՝ /app/[locale]/tacotranslate.tsx, որտեղ մենք կիրականացնենք TacoTranslate պրովայդերը։

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

Ուշադրություն դարձրեք 'use client';՝ որը ցույց է տալիս, որ սա հաճախորդային կոմպոնենտ է։

Երբ կոնտեքստի պրովայդերը արդեն պատրաստ է, ստեղծեք ֆայլ՝ /app/[locale]/layout.tsx, որը հանդիսանում է մեր հավելվածի արմատային layout-ը։ Ուշադրություն դարձրեք, որ այս ուղին ունի թղթապանակ, որը օգտագործում է Dynamic Routes, որտեղ [locale] հանդիսանում է դինամիկ պարամետրը։

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

Առաջինն, ինչ պետք է նկատել՝ մենք օգտագործում ենք մեր Dynamic Route պարամետրը՝ [locale] տվյալ լեզվի թարգմանություններ ստանալու համար։ Բացի այդ, generateStaticParams ապահովում է, որ ձեր նախագծի համար ակտիվացված բոլոր locale կոդերը նախապես գեներացվեն։

Հիմա եկեք կառուցենք մեր առաջին էջը։ Ստեղծեք /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!" />
	);
}

Ուշադրություն դարձրեք revalidate փոփոխականին, որը ասում է Next.js-ին վերակառուցել էջը 60 վայրկյանից հետո և պահպանել ձեր թարգմանությունները արդիական։

Քայլ 4: Սերվերային կողմի ռենդերինգի իրականացում

TacoTranslate-ը աջակցում է սերվերային կողմի ռենդերինգին։ Սա մեծապես բարելավում է օգտվողի փորձը՝ թարգմանված բովունակտությունը ցուցադրելով անմիջապես, փոխարենը սկզբում թարգմանված չլինող բովանդակության ակնթարթային երևումին։ Բացի այդ, մենք կարող ենք խուսափել հաճախորդի կողմից լրացուցիչ ցանցային հարցումներից, քանի որ արդեն ունենք այդ էջի համար անհրաժեշտ թարգմանությունները։

Սերվերային կողմի ռենդերինգը կարգավորելու համար՝ ստեղծեք կամ փոփոխեք /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};
};

Փոխեք isProduction ստուգումը ձեր կազմաձևին համապատասխան։ Եթե true, TacoTranslate‑ը կցուցադրի հրապարակային API բանալին։ Եթե մենք տեղական, թեստային կամ ստեյջինգ միջավայրում ենք (isProduction is false), մենք կօգտագործենք գաղտնի read/write API բանալին՝ որպեսզի նոր տեքստերը ուղարկվեն թարգմանության։

Որպեսզի երթուղավորումն ու վերաուղղումն աշխատեն այնպես, ինչպես սպասվում է, մեզ պետք կլինի ստեղծել ֆայլը՝ /middleware.ts. Օգտագործելով Middleware, մենք կարող ենք վերաուղղել օգտատերերին դեպի այն էջերը, որոնք ներկայացված են իրենց նախընտրած լեզվով։

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

Համոզվեք, որ matcher-ը կարգավորված է համաձայն Next.js Middleware-ի փաստաթղթերի։

Կլայենտում դուք կարող եք փոխել locale կուկին՝ որպեսզի փոխեք օգտվողի նախընտրած լեզուն։ Խնդրում ենք դիտել ամբողջական օրինակային կոդը՝ գաղափարներ ստանալու, թե ինչպես դա անել։

Քայլ 5: Տեղակայեք և ստուգեք!

Ամեն ինչ պատրաստ է։ Ձեր React հավելվածը այժմ ավտոմատ կերպով կթարգմանվի, երբ Translate կոմպոնենտում ավելացնեք ցանկացած տող։ Նշենք, որ միայն այն միջավայրերը, որոնց API բանալին ունի read/write թույլտվություններ, կկարողանան ստեղծել թարգմանման համար նոր տողեր։ Մենք խորհուրդ ենք տալիս ունենալ փակ և ապահով ստուգողական (staging) միջավայր, որտեղ կարող եք փորձարկել ձեր արտադրական հավելվածը նման API բանալով՝ ավելացնելով նոր տողեր նախքան կենդանի թողնելը։ Սա կխանգարի որևէ մեկին գողանալ ձեր գաղտնի API բանալին և հնարավոր է կանխի ձեր թարգմանական նախագծի անհարկի մեծանումը՝ նոր, ոչ առնչվող տողեր ավելացնելու միջոցով։

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!