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 кілтімен өндірістік қосымшаны сынап, жаңа мәтіндерді қоса алатындай жабық және қауіпсіз staging ортасын пайдалануды ұсынамыз. Бұл сіздің құпия API кілтіңіздің ұрлануын болдырмайды және қатысы жоқ жаңа мәтіндерді қосу арқылы аударма жобаңызды қажетсіз түрде үлкейтіп жіберу қаупінен сақтайды.

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

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