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-ը առաջադեմ AI-ի միջոցով ավտոմատ թարգմանում է ձեր տեքստերը ցանկացած լեզվով և ազատում է ձեզ 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: «Թղթապանակը», որտեղ կհավատվեն կամ կհանձնվեն ձեր տողերը (strings), օրինակ՝ ձեր կայքի 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_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-ն թույլ է տալիս ձեր թարգմանությունները մատուցել սերվերային կողմում (server-side rendering). Սա զգալիորեն բարելավում է օգտվողի փորձը՝ երբ թարգմանված բովանդակությունը ցուցադրվում է անմիջապես, այլ ոչ թե սկզբում կարճ ժամանակով երևում է չթարգմանված նյութը։ Բացի այդ, կարող ենք խուսափել հաճախորդային կողմի ցանցային հարցումներից, քանի որ արդեն ունենք բոլոր անհրաժեշտ թարգմանությունները։

Սկսելու ենք՝ ստեղծելով կամ փոփոխելով /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 թույլտվություններ, կարող են ստեղծել նոր՝ թարգմանման ենթակա տողեր։ Խորհուրդ ենք տալիս ունենալ փակ և ապահով փորձարկման միջավայր, որտեղ կարող եք փորձարկել ձեր արտադրական հավելվածը նման 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 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!