App Router қолданатын Next.js қосымшасында интернационализацияны қалай жүзеге асыруға болады

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

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

Бұл нұсқаулық App Router қолданатын Next.js қосымшаларына арналған.
Егер сіз Pages 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Біз жақында автоматты түрде TACOTRANSLATE_API_KEY және TACOTRANSLATE_PROJECT_LOCALE анықтайтын боламыз.

Клиентті бөлек файлда құру оны кейін қайта пайдалануды жеңілдетеді. getLocales — бұл кейбір кірістірілген қате өңдеуі бар жай утилиталық функция ғана. Енді /app/[locale]/tacotranslate.tsx атты файл жасаңыз, онда біз TacoTranslate провайдерін жүзеге асырамыз.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Клиент компонент екенін көрсететін 'use client';-ке назар аударыңыз.

Контекст провайдері дайын болғаннан кейін, қолданбамыздың негізгі layout файлын жасау үшін /app/[locale]/layout.tsx атты файл құрыңыз. Бұл жолда Dynamic Routes пайдаланатын буманың барын ескеріңіз; онда [locale] — динамикалық параметр.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Ең алдымен назар аударатын жайт: біз сол тілдің аудармаларын алу үшін Dynamic Route параметрі [locale] пайдаланып жатырмыз. Сонымен қатар, generateStaticParams жобаңызда қосылған барлық локаль кодтарының алдын ала рендерленуін қамтамасыз етеді.

Енді бірінші бетті жасайық! /app/[locale]/page.tsx файлын жасаңыз.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Next.js-ке бетті 60 секундтан кейін қайта құруды және аудармаларыңызды жаңартып тұруды айтатын revalidate айнымалысына назар аударыңыз.

4-қадам: Сервер жағында рендерлеуді жүзеге асыру

TacoTranslate сервер жағындағы рендерлеуді қолдайды. Бұл пайдаланушы тәжірибесін айтарлықтай жақсартады — аудармаланған мазмұнды бірден көрсетіп, алдымен аудармаланбаған мазмұнның жыпылықтап көрінуіне жол бермейді. Сонымен қатар, клиент жағында желі сұрауларын өткізіп жіберуге болады, себебі пайдаланушы қарап тұрған беттің аудармалары бізде бұрыннан бар.

Сервер жағындағы рендерингті баптау үшін /next.config.js файлын жасаңыз немесе өзгертіңіз:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Орнатуыңызға сәйкес isProduction тексерісін өзгертіңіз. Егер true болса, TacoTranslate қоғамдық API кілтін көрсетеді. Егер біз жергілікті, тесттік немесе staging ортада болсақ (isProduction is false), жаңа жолдардың аудармаға жіберілуін қамтамасыз ету үшін құпия read/write API кілтін қолданамыз.

Маршрутизация мен қайта бағыттау күтілгендей жұмыс істеуі үшін /middleware.ts атты файл құруымыз керек. Middleware көмегімен пайдаланушыларды олардың таңдаған тілінде көрсетілген беттерге бағыттай аламыз.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

matcher конфигурациясын Next.js Middleware құжаттамасына сәйкес орнатқаныңызға көз жеткізіңіз.

Клиент жағында пайдаланушының қалаған тілін өзгерту үшін locale cookie файлын өзгерте аласыз. Қалай істеуге болатыны туралы идеялар алу үшін толық мысал кодын қараңыз!

5‑қадам: Жариялап, тексеріңіз!

Біз аяқтадық! Енді Translate компонентіне кез келген мәтін жолдарын қосқан кезде сіздің React қолданбаңыз автоматты түрде аударылады. Назар аударыңыз: 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 Pages 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!