Pages Router қолданатын Next.js қосымшасында халықаралықтандыруды қалай жүзеге асыруға болады

Әлем жаһанданған сайын, веб-әзірлеушілер үшін әртүрлі елдер мен мәдениеттерден келген пайдаланушыларға арналған қолданбалар жасау маңыздырақ бола түсуде. Осы мақсатқа жетудің негізгі тәсілдерінің бірі — интернационализация (i18n), ол сізге қолданбаңызды әртүрлі тілдерге, валюталарға және күн мен уақыт форматтарына бейімдеуге мүмкіндік береді.

Бұл оқулықта біз серверлік рендерингті қолдана отырып, React Next.js қолданбаңызға интернационализацияны қалай қосуға болатынын қарастырамыз. TL;DR: Толық мысалды мұнда қараңыз.

Бұл нұсқаулық Pages Router қолданатын Next.js қосымшалары үшін арналған.
Егер сіз 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: Әдепкі резервтік локаль коды. Бұл мысалда біз оны ағылшын үшін 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 қасиеттері. Ескеріңіз, getTacoTranslateStaticProps ішіндегі revalidate әдепкі бойынша 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!"/>;
}

Енді сіз барлық React компоненттеріңізде жолдарды аудару үшін Translate компонентін пайдалана аласыз.

import {Translate} from 'tacotranslate/react';

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

5-қадам: Жариялаңыз және тексеріңіз!

Біз аяқтадық! Енді сіз Translate компонентіне кез келген мәтіндерді қосқан кезде, сіздің React қолданбаңыз автоматты түрде аударылатын болады. Назар аударыңыз: API кілтіне арналған read/write рұқсаттары бар орталар ғана аударылатын жаңа мәтіндерді жасай алады. Біз өндірістік қолданбаңызды осындай API кілтімен тексеріп, тікелей эфирге шықпас бұрын жаңа мәтіндерді қосу үшін жабық және қауіпсіз сынақ ортасын құруды ұсынамыз. Бұл сіздің құпия API кілтіңізді кім болса да кім болса да ұрлап кетуінен сақтайды және аударма жобаңызды жаңа, байланысы жоқ мәтіндермен үлкейтіп жіберу ықтималдығын азайтады.

Біздің GitHub профиліміздегі толық мысалды міндетті түрде қарап шығыңыз. Онда сондай-ақ бұл әрекетті App Router арқылы қалай орындауға болатыны туралы мысалды да таба аласыз! Егер қандай да бір қиындыққа тап болсаңыз, еркін түрде байланысыңыз, біз қуана-қуана көмектесеміз.

TacoTranslate сіздің React қосымшаларыңызды 75-тен астам тілге және сол тілдерден автоматты түрде және жылдам локализациялауға мүмкіндік береді. Бүгін-ақ бастаңыз!