Ինչպես իրականացնել միջազգայինացում 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. Օրինակ՝ կարող եք դրանք ավելացնել ձեր project's արմատում գտնվող .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‑ը։ Ավելին՝ origins‑ների մասին կարդացեք այստեղ։

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

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

Քայլ 5: Տեղադրել և փորձարկել!

Ամեն ինչ պատրաստ է։ Ձեր React հավելվածը այժմ ավտոմատ կերպով կթարգմանվի, երբ ավելացնեք որևէ տող Translate կոմպոնենտում։ Խնդրում ենք նկատի ունենալ, որ միայն այն միջավայրերը, որոնց API բանալին ունի read/write թույլտվություններ, կարող են ստեղծել նոր տողեր թարգմանության համար։ Խորհուրդ ենք տալիս ունենալ փակ և ապահով staging միջավայր, որտեղ կարող եք թեստավորել ձեր production հավելվածը նման 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!