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 мекенжайы. Origin туралы толығырақ осы жерден оқыңыз.

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 компонентіне кез келген мәтінді қосқанда, сіздің Next.js қосымшаңыз автоматты түрде аударылатын болады. Назар аударыңыз: API кілтінде read/write рұқсаты бар орта ғана аударуға арналған жаңа жолдарды құра алады. Өндірістік қосымшаңызды мұндай API кілтімен тексеріп, іске қосардан бұрын жаңа жолдарды қосу үшін жабық және қорғалған тестілеу ортасын ұстауды ұсынамыз. Бұл сіздің құпия API кілтіңіздің ұрлануын болдырмайды және аударма жобаңызды жаңа, қатысы жоқ жолдарды қосып, қажетсіз түрде ұлғайтудан сақтайды.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!