Ինչպես իրականացնել միջազգայինացում 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';՝ որը ցույց է տալիս, որ սա կլայենտ կոմպոնենտ է։

Երբ կոնտեքստի provider-ը այժմ պատրաստ է, ստեղծեք /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 փաստաթղթավորման.

Հաճախորդի կողմում կարող եք փոխել 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!