App Router ашиглаж буй Next.js апп-д олон хэлний дэмжлэг (i18n)-ийг хэрхэн хэрэгжүүлэх вэ?

Дэлхий ертөнц улам олон улсын шинжтэй болж буй тул вэб хөгжүүлэгчдэд янз бүрийн улс орон, соёлт хэрэглэгчдэд тохирсон програмуудыг хөгжүүлэх нь илүү чухал болж байна. Үүний нэг гол арга нь олон улсынчлах (i18n) бөгөөд энэ нь таны програмыг янз бүрийн хэл, валют, огнооны форматуудтай нийцүүлэх боломжийг олгодог.

Энэхүү нийтлэлд бид сервер талын рендерингтэйгээр React Next.js програмдаа олон улсынчлахыг хэрхэн нэмэх тухай танилцуулах болно. TL;DR: Бүрэн жишээг эндээс үзнэ үү.

Энэхүү гарын авлага нь App Router ашиглаж байгаа Next.js програмуудад зориулагдсан.
Хэрэв та Pages Router ашиглаж байгаа бол энэ зааварыг оронд нь үзнэ үү.

Алхам 1: i18n номын санг суулгах

Next.js програмдаа олон хэлний дэмжлэг (i18n) хэрэгжүүлэхийн тулд эхлээд i18n номын сан сонгоно. Ашиглагддаг хэд хэдэн алдартай номын санууд бий, үүнд next-intl. Гэсэн хэдий ч энэ жишээнд бид TacoTranslate ашиглана.

TacoTranslate нь дэвшилтэт хиймэл оюун ухааныг ашиглан таны стрингүүдийг хүссэн ямар ч хэл рүү автоматаар орчуулж, JSON файлуудыг удирдах уйтгартай ажлаас чөлөөлдөг.

Терминал дээрээ npm ашиглан суулгая:

npm install tacotranslate

Алхам 2: TacoTranslate-д үнэгүй данс үүсгээрэй.

Модулийг суулгасан тул одоо TacoTranslate данс, орчуулгын төсөл болон холбогдох API түлхүүрүүдийг үүсгэх цаг боллоо. Энд бүртгүүлнэ үү. Үүнтэй зэрэгцэн үнэгүй бөгөөд кредит карт оруулах шаардлагагүй.

TacoTranslate-ийн UI-д төсөл үүсгээд API keys таб руу орно уу. Нэг 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: Анхдагч (fallback) локалын код. Энэ жишээнд бид үүнийг англи хэлний хувьд en гэж тогтооно.
• TACOTRANSLATE_ORIGIN: Таны текстүүд хадгалагдах "фолдер" буюу байршил, жишээлбэл таны вэбсайтын URL. Эх үүсвэрийн талаар эндээс дэлгэрэнгүй уншаарай.

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'; гэдгийг анхаарна уу.

Контекст провайдер бэлэн болсон тул /app/[locale]/layout.tsx нэртэй файлыг үүсгээрэй — энэ нь манай програмын үндсэн layout буюу root layout юм. Энэ зам нь 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-р алхам: Байршуулаад туршиж үзэх!

Бэлэн боллоо! Таны React програм одооноос эхлэн Translate компонент руу ямар ч мөр нэмсэн үед автоматаар орчуулагдах болно. Анхаарна уу: 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 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!