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

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

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

Այս ուղեցույցը նախատեսված է Next.js հավելվածների համար, որոնք օգտագործում են Pages Router.
Եթե դուք օգտագործում եք App 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 բանալին երբեք չբացահայտվի հաճախորդային (client-side) արտադրական միջավայրերում։

Մենք նաև կավելացնենք երկու լրացուցիչ միջավայրի փոփոխական՝ 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-ը ձեր հավելվածին ինտեգրելու համար հարկավոր է ստեղծել մի 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Շուտով ավտոմատ կերպով սահմանելու ենք TACOTRANSLATE_API_KEY.

Կլիենտը առանձին ֆայլում ստեղծելը հեշտացնում է այն հետագայում կրկին օգտագործելը։ Այժմ, օգտագործելով հարմարեցված /pages/_app.tsx, մենք կավելացնենք TacoTranslate պրովայդերը։

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Եթե արդեն ունեք հարմարեցված pageProps և _app.tsx, խնդրում ենք ընդլայնել սահմանումը վերևում բերված հատկություններով և կոդով։

Քայլ 4: Սերվերային կողմի ռենդերավորման իրականացում

TacoTranslate-ը թույլ է տալիս ձեր թարգմանությունները ռենդերել սերվերի կողմում։ Սա մեծապես բարելավում է օգտվողի փորձը՝ թարգմանված բովանդակությունը ցուցադրելով անմիջապես, այլ ոչ թե սկզբում կարճ ժամանակով ցույց տալով չթարգմանված բովանդակությունը։ Բացի այդ, կարող ենք բաց թողնել հաճախորդային կողմի ցանցային հարցումները, քանի որ արդեն ունենք բոլոր անհրաժեշտ թարգմանությունները։

Մենք կսկսենք ստեղծելով կամ փոփոխելով /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Փոխեք isProduction ստուգումը՝ ώστε այն համապատասխան լինի ձեր կարգավորմանը. Եթե true, TacoTranslate-ը կցուցադրի հանրային API բանալին։ Եթե մենք տեղական, թեստային կամ նշաձև (staging) միջավայրում ենք (isProduction is false), մենք կօգտագործենք գաղտնի read/write API բանալին՝ ապահովելու համար, որ նոր տեքստերը ուղարկվեն թարգմանության։

Մինչ այժմ մենք Next.js հավելվածը կարգավորել ենք ընդամենը աջակցվող լեզուների ցուցակով։ Հաջորդ քայլը կլինի բոլոր ձեր էջերի համար թարգմանություններ ստանալը։ Դա անելու համար՝ ըստ ձեր պահանջների, դուք կօգտագործեք կամ getTacoTranslateStaticProps կամ getTacoTranslateServerSideProps։

Այս ֆունկցիաները ընդունում են երեք արգումենտ՝ մեկը Next.js Static Props Context օբյեկտ, TacoTranslate-ի կարգավորումը և ոչ պարտադիր Next.js հատկություններ։ Նկատեք, որ revalidate‑ը getTacoTranslateStaticProps‑ում ստանդարտ կերպով սահմանված է 60‑ով, որպեսզի ձեր թարգմանությունները մնան արդիական։

Էջում ցանկացած ֆունկցիա օգտագործելու համար՝ ենթադրենք, որ ունեք հետևյալ էջի ֆայլը՝ /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Հիմա դուք պետք է կարողանաք օգտագործել Translate կոմպոնենտը՝ ձեր բոլոր React կոմպոնենտներում տողերը թարգմանելու համար։

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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

Ամենը պատրաստ է։ Ձեր React հավելվածը այժմ ավտոմատ կերպով թարգմանվելու է, երբ Translate կոմպոնենտում ավելացնեք որևէ տող։ Նշենք, որ միայն այն միջավայրերը, որոնց API բանալուն վերապահված են read/write թույլտվությունները, կկարողանան ստեղծել նոր տողեր՝ թարգմանման համար։ Խորհուրդ ենք տալիս ունենալ փակ և անվտանգ ստեյջինգ միջավայր, որտեղ կարող եք թեստավորել ձեր արտադրական հավելվածը նման API բանալով՝ նախքան հրապարակումը ավելացնելով նոր տեքստեր։ Դա կկանխի ոչ գրագետ անձանց ձեր գաղտնի API բանալին գողանալը և հնարավոր է լցնի ձեր թարգմանական նախագիծը՝ ավելացնելով նոր, անառնչվող տեքստեր։

Խնդրում ենք անպայման դիտել ամբողջական օրինակն մեր GitHub պրոֆիլում։ Այստեղ նաև կգտնեք օրինակ, որը ցույց է տալիս, թե ինչպես դա անել՝ օգտագործելով App Router։ Եթե հանդիպեք խնդիրների, ազատ զգացեք մեզ գրել, և մենք ուրախությամբ կօգնենք։

TacoTranslate-ը թույլ է տալիս ձեր React հավելվածները ավտոմատ կերպով տեղայնացնել ավելի քան 75 լեզուների միջև։ Սկսեք այսօր!