Pages Router қолданатын Next.js қосымшасында көптілділікті қалай енгізуге болады?

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

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

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