Ինչպես իրականացնել բազմալեզվայնացում (i18n) 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 հավելվածի միջերեսում ստեղծեք նախագիծ և անցեք դրա 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_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 on 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 իրավունքներ, կարող են ստեղծել թարգմանման համար նոր տողեր։ Խորհուրդ ենք տալիս ունենալ փակ և ապահով վերստացման (staging) միջավայր, որտեղ կարող եք փորձարկել ձեր արտադրական հավելվածը նման API բանալիով՝ նախօրոք ավելացնելով նոր տողեր մինչև հրապարակումը։ Սա կհաշվի նրանց հասնելուց, որ ոչ ոք չգողանա ձեր գաղտնի API բանալին և կխուսափի ձեր թարգմանական նախագծի ավելորդ և ոչ առնչվող տողերով լցվելուց։

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

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