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

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

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

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

Այս ուղեցույցը նախատեսված է 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: Նախնական (fallback) լոկալի կոդը։ Այս օրինակով մենք այն կսահմանենք որպես en՝ անգլերենի համար.
• TACOTRANSLATE_ORIGIN: Դա այն «թղթապանակն» է, որտեղ կպահվեն ձեր տողերը, օրինակ՝ ձեր կայքի URL-ը։ Ավելին՝ աղբյուրների մասին կարդացեք այստեղ.

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