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