Next.js հավելվածների միջազգայինացման (i18n) լավագույն լուծումը

Ինչպես է աշխատում

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

Մենք նաև կավելացնենք ևս երկու շրջակա միջավայրի փոփոխական՝ TACOTRANSLATE_DEFAULT_LOCALE և TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Լռելյայն (default) փոխհատուցման տեղականության (locale) կոդը։ Այս օրինակով այն սահմանվում է որպես 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, խնդրում ենք ընդլայնել սահմանումը վերևում նշված հատկություններով և կոդով։

Step 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 բանալին։ Եթե մենք տեղական, թեստային կամ ստեյջինգ միջավայրում ենք (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: Տեղակայեք և փորձարկեք!

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