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-қадам: Орнату және тексеру!

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