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

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

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

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

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

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

TacoTranslate-ը առաջատար արհեստական բանականության (AI) օգնությամբ ավտոմատաբար թարգմանում է ձեր տողերը ցանկացած լեզվով և ազատում է ձեզ 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-ը ինտեգրելու համար անհրաժեշտ է ստեղծել client՝ օգտագործելով ավելի վաղ նշված 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 բանալին։ Եթե մենք տեղական, փորձնական կամ 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-ի փաստաթղթերի.

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

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