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-тен астам тілге және сол тілдерден автоматты түрде және жылдам локализациялауға мүмкіндік береді. Бүгін-ақ бастаңыз!