Ինչպես իրականացնել բազմալեզվայնություն (i18n) 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) տեղայնության (locale) կոդն է։ Այս օրինակով մենք այն կսահմանենք որպես 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'; նշանին, որը ցույց է տալիս, որ սա հաճախորդային կոմպոնենտ է։

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

Սերվերի կողմի վերարտադրությունը (server-side rendering) կարգավորելու համար՝ ստեղծեք կամ խմբագրեք /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 բանալին՝ ապահովելու համար, որ նոր տեքստերը ուղարկվեն թարգմանության։

Որպեսզի ուղղորդումն (routing) և վերուղղումը (redirection) աշխատեն ակնկալվող կերպով, հարկ կլինի ստեղծել /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-ի փաստաթղթերի.

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

Քայլ 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!