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

Աշխարհի գլոբալացման ընթացքում վեբ ծրագրավորողների համար ավելի ու ավելի կարևոր է ստեղծել այնպիսի հավելվածներ, որոնք կարող են հոգալ տարբեր երկրների և մշակույթների օգտատերերի կարիքները։ Մեկ հիմնական միջոցներից biri միջազգայինացումը (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-ը։ Ավելին սկզբնաղբյուրների մասին կարդացեք այստեղ.

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';՝ որը ցույց է տալիս, որ սա հաճախորդային կոմպոնենտ է։

Հիմա երբ context-ի պրովայդերը պատրաստ է, ստեղծեք ֆայլ՝ անվանված /app/[locale]/layout.tsx, որը հանդիսանում է մեր հավելվածի արմատային լեյաութը։ Նշեք, որ այս ուղին պարունակում է թղթապանակ, որը օգտագործում է 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 բանալին։ Եթե մենք տեղական, փորձարկման կամ staging միջավայրում ենք (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 իրավունքները, կկարողանան ստեղծել նոր տողեր՝ թարգմանման համար։ Խորհուրդ ենք տալիս ունենալ փակ և უსაფრთხված ստեյջինգ միջավայր, որտեղ կարող եք այդպիսի 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!