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