Next.js tətbiqində App Router istifadə edən bir tətbiqdə beynəlxalqlaşdırmanı necə həyata keçirmək olar

Dünya daha da qloballaşdıqca, veb tərtibatçılar üçün müxtəlif ölkələrdən və mədəniyyətlərdən olan istifadəçilərə xidmət edə bilən tətbiqlər yaratmaq getdikcə daha vacib olur. Bunu həyata keçirməyin əsas yollarından biri beynəlxalqlaşdırma (i18n) vasitəsilədir, bu da tətbiqinizi müxtəlif dillərə, valyutalara və tarix formatlarına uyğunlaşdırmağa imkan verir.

Bu məqalədə, React Next.js tətbiqinizə server tərəfi renderləşdirmə ilə birlikdə beynəlxalqlaşdırma necə əlavə ediləcəyini araşdıracağıq. TL;DR: Tam nümunəyə buradan baxın.

Bu bələdçi App Router istifadə edən Next.js tətbiqləri üçündür.
Əgər siz Pages Router istifadə edirsinizsə, onun əvəzinə bu bələdçiyə baxın.

1-ci addım: i18n kitabxanasını quraşdırın

Next.js tətbiqinizdə beynəlxalqlaşdırmanı həyata keçirmək üçün əvvəlcə bir i18n kitabxanası seçəcəyik. Bir neçə məşhur kitabxana mövcuddur, o cümlədən next-intl. Ancaq bu nümunədə TacoTranslate istifadə edəcəyik.

TacoTranslate qabaqcıl AI texnologiyasından istifadə edərək sətirlərinizi istənilən dilə avtomatik tərcümə edir və sizi JSON fayllarının sıxıcı idarəetməsindən azad edir.

Terminalınızda npm istifadə edərək onu quraşdıraq:

npm install tacotranslate

2-ci addım: Pulsuz TacoTranslate hesabı yaradın

İndi modul quraşdırıldıqdan sonra, TacoTranslate hesabınızı, tərcümə layihənizi və əlaqəli API açarlarını yaratmaq vaxtıdır. Hesab yaradın burada. Bu pulsuzdur və kredit kartı əlavə etməyinizi tələb etmir.

TacoTranslate tətbiqinin istifadəçi interfeysində bir layihə yaradın və onun API açarları sekmesine daxil olun. Bir read açarı və bir read/write açarı yaradın. Bunları mühit dəyişənləri kimi yadda saxlayacağıq. read açarına public deyirik, read/write açarı isə secret adlanır. Məsələn, onları layihənizin kök qovluğundakı .env faylına əlavə edə bilərsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Müştəri tərəfi istehsal mühitinə gizli read/write API açarını heç vaxt sızdırmadığınızdan əmin olun.

Biz həmçinin iki əlavə ətraf mühit dəyişəni əlavə edəcəyik: TACOTRANSLATE_DEFAULT_LOCALE və TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Defolt ehtiyat lokal kodu. Bu nümunədə, onu İngilis dili üçün en olaraq təyin edəcəyik.
• TACOTRANSLATE_ORIGIN: Sətirlərinizin saxlanılacağı “qovluq”, məsələn, veb saytınızın URL-i. Burada originlər haqqında daha ətraflı oxuyun.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

3-cü addım: TacoTranslate-in qurulması

TacoTranslate-i tətbiqinizə inteqrasiya etmək üçün əvvəlki API açarları ilə bir müştəri yaratmalısınız. Məsələn, /tacotranslate-client.js adlı bir fayl yaradın.

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;

Biz tezliklə avtomatik olaraq TACOTRANSLATE_API_KEY və TACOTRANSLATE_PROJECT_LOCALE dəyişənlərini təyin edəcəyik.

Klienti ayrıca fayl şəklində yaratmaq, onu sonradan yenidən istifadə etməyi asanlaşdırır. getLocales yalnız bir neçə daxili səhv idarə etməsi olan utilit funksiyasıdır. İndi /app/[locale]/tacotranslate.tsx adlı fayl yaradın, burada TacoTranslate təminatçısını tətbiq edəcəyik.

'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>
	);
}

Qeyd edin ki, 'use client'; bu komponentin müştəri komponenti olduğunu göstərir.

Kontekst provayderi artıq istifadəyə hazır olduqdan sonra, /app/[locale]/layout.tsx adlı fayl yaradın, bu fayl tətbiqimizdə əsas layout-dur. Qeyd edin ki, bu yolda Dynamic Routes istifadə edilən bir qovluq var, burada [locale] dinamik parametrdir.

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>
	);
}

Burada qeyd edilməli ilk şey odur ki, biz həmin dil üçün tərcümələri əldə etmək üçün Dynamic Route parametrimiz olan [locale] istifadə edirik. Bundan əlavə, generateStaticParams layihəniz üçün aktivləşdirdiyiniz bütün dil kodlarının əvvəlcədən render olunmasını təmin edir.

İndi gəlin ilk səhifəmizi yaradaq! /app/[locale]/page.tsx adlı bir fayl yaradın.

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

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

Qeyd edin ki, revalidate dəyişəni Next.js-ə səhifəni 60 saniyədən sonra yenidən qurmasını və tərcümələrinizi aktual saxlamasını bildirir.

4-cü addım: Server tərəfində renderləmə implementasiyası

TacoTranslate server tərəfi renderini dəstəkləyir. Bu, tərcümə olunmuş məzmunu dərhal göstərməklə istifadəçi təcrübəsini xeyli yaxşılaşdırır, əvvəlcə tərcümə olunmamış məzmunun qısa müddətli görünməsinin qarşısını alır. Bundan əlavə, müştəri tərəfdə şəbəkə sorğularını keçə bilərik, çünki istifadəçinin baxdığı səhifə üçün lazım olan tərcümələr onsuz da mövcuddur.

Server tərəfli renderləşdirməni qurmaq üçün /next.config.js faylını yaradın və ya dəyişdirin:

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 yoxlamasını öz mühitinizə uyğunlaşdırın. Əgər true olarsa, TacoTranslate public API açarını göstərəcək. Əgər biz lokal, test, və ya staging mühitindəyiksə (isProduction is false), yeni sətirlərin tərcüməyə göndərildiyinə əmin olmaq üçün gizli read/write API açarını istifadə edəcəyik.

Routing və yönləndirmənin gözlənildiyi kimi işləməsini təmin etmək üçün, /middleware.ts adlı bir fayl yaratmalıyıq. Middleware istifadə edərək, istifadəçiləri üstünlük verdikləri dildə təqdim olunan səhifələrə yönləndirə bilərik.

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 sənədlərinə uyğun olaraq qurduğunuza əmin olun.

Müştəri tərəfində istifadəçinin üstünlük verdiyi dili dəyişdirmək üçün locale kukisini dəyişə bilərsiniz. Necə edəcəyiniz barədə fikirlər üçün tam nümunə koduna baxın!

5-ci Addım: Yayınlayın və test edin!

İş bitdi! İndi React tətbiqinizə hər hansı bir sətri Translate komponentinə əlavə etdiyiniz zaman avtomatik olaraq tərcümə olunacaq. Qeyd edin ki, yalnız API açarında read/write icazəsi olan mühitlər yeni tərcümə sətrləri yarada biləcəklər. Biz tövsiyə edirik ki, belə bir API açarı ilə tətbiqinizi canlıya keçmədən əvvəl sınaya biləcəyiniz qapalı və təhlükəsiz bir sınaq (staging) mühiti olsun və yeni sətrlər əlavə edin. Bu, kimsənin gizli API açarınızı oğurlamasının qarşısını alacaq və potensial olaraq tərcümə layihənizin əlaqəsiz yeni sətrlərlə dolmasının qarşısını tutacaq.

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!