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

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

Осы оқулықта біз React Next.js қолданбаңызға серверлік рендерлеумен бірге халықаралықтандыруды қалай қосуға болатынын қарастырамыз. TL;DR: Толық мысалды мына жерден қараңыз.

Бұл нұсқаулық Pages Router қолданатын Next.js қосымшалары үшін.
Егер сіз App Router пайдалансаңыз, оның орнына осы нұсқаулықты қараңыз.

1-қадам: i18n кітапханасын орнатыңыз

Next.js қосымшаңызда халықаралықтандыруды іске асыру үшін алдымен 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 қасиеттері. Ескеріңіз, 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!"/>;
}

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