Next.js tətbiqində, App Router istifadə edildikdə, beynəlxalqlaşdırmanı necə tətbiq etmək olar

Aləmdə getdikcə qloballaşma artdıqca, veb inkişaf etdiricilərin müxtəlif ölkə və mədəniyyətlərdən olan istifadəçilərə uyğunlaşa bilən tətbiqlər yaratmaları daha vacib olur. Bunu əldə etməyin əsas yollarından biri beynəlxalqlaşdırma (i18n)-dır; bu, 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əfində renderləmə ilə beynəlxalqlaşdırmanı necə əlavə edəcəyimizi 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 Pages Router istifadə edirsinizsə, onun əvəzinə bu bələdçiyə baxın.

Addım 1: i18n kitabxanası quraşdırın

Next.js tətbiqinizdə beynəlmiləlləşdirməni (i18n) tətbiq etmək üçün əvvəlcə bir i18n kitabxanası seçəcəyik. Bir neçə məşhur kitabxana var, o cümlədən next-intl. Lakin bu nümunədə biz TacoTranslate-dən istifadə edəcəyik.

TacoTranslate ən müasir süni intellektdən istifadə edərək sətirlərinizi istənilən dilə avtomatik tərcümə edir və sizi JSON fayllarının yorucu idarə edilməsindən azad edir.

Gəlin terminalınızda npm istifadə edərək onu quraşdıraq:

npm install tacotranslate

Addım 2: Pulsuz TacoTranslate hesabı yaradın

Modulu quraşdırdığınıza görə, indi TacoTranslate hesabınızı, tərcümə layihənizi və əlaqəli API açarlarını yaratmaq vaxtıdır. Burada hesab yaradın. 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ı tabına keçin. Bir read açarı və bir read/write açarı yaradın. Onları mühit dəyişənləri kimi saxlayacağıq. read açarını public adlandırırıq, read/write açarı isə secret adlanır. Məsələn, onları layihənizin kökündəki .env faylına əlavə edə bilərsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gizli read/write API açarını müştəri tərəfdəki istehsal mühitlərinə heç vaxt sızdırmadığınızdan əmin olun.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan ehtiyat locale kodu. Bu nümunədə onu ingilis dili üçün en olaraq təyin edəcəyik.
• TACOTRANSLATE_ORIGIN: Sətirlərinizin saxlanılacağı “qovluq”, məsələn saytınızın URL-i. Originlər haqqında daha ətraflı məlumatı burada oxuyun.

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

Addım 3: TacoTranslate-i qurmaq

TacoTranslate-i tətbiqinizə inteqrasiya etmək üçün əvvəlki API açarlarından istifadə edərək bir klient 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;

Tezliklə TACOTRANSLATE_API_KEY və TACOTRANSLATE_PROJECT_LOCALE avtomatik olaraq təyin ediləcək.

Müştərini ayrı bir faylda yaratmaq onu daha sonra yenidən istifadə etməyi asanlaşdırır. getLocales sadəcə bəzi daxili səhv idarəetməsi olan bir köməkçi funksiyadır. İndi /app/[locale]/tacotranslate.tsx adlı bir fayl yaradın, burada biz TacoTranslate provayderini 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>
	);
}

Bu bir müştəri komponenti olduğunu göstərən 'use client'; qeyd edin.

Kontekst təminatçısı indi hazır olduqdan sonra, tətbiqimizdə əsas layout olan /app/[locale]/layout.tsx adlı bir fayl yaradın. Qeyd edin ki, bu yol Dynamic Routes-dan istifadə edən bir qovluğa malikdir və 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 ilk qeyd edilməli məqam odur ki, biz həmin dil üçün tərcümələri əldə etmək üçün Dynamic Route parametrimiz [locale]dən istifadə edirik. Əlavə olaraq, generateStaticParams layihənizdə aktiv etdiyiniz bütün locale kodlarının əvvəlcədən render olunmasını təmin edir.

İndi gəlin ilk səhifəmizi quraq! /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ə sonra yenidən qurmağı və tərcümələrinizi güncəldə saxlamağı tapşırır.

4-cü addım: Server tərəfli renderləmənin tətbiqi

TacoTranslate server tərəfdən renderi dəstəkləyir. Bu, istifadəçi təcrübəsini xeyli yaxşılaşdırır — tərcümə olunmamış məzmunun əvvəlcə görünməsi əvəzinə tərcümə olunmuş məzmun dərhal göstərilir. Bundan əlavə, istifadəçinin baxdığı səhifə üçün lazım olan tərcümələr artıq mövcud olduğundan, klientdə şəbəkə sorğularını keçə bilərik.

Server tərəfi 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};
};

Öz quruluşunuza uyğunlaşdırmaq üçün isProduction yoxlamasını dəyişdirin. Əgər true olsa, TacoTranslate ictimai API açarını göstərəcək. Əgər biz lokal, test və ya staging mühitindəsə (isProduction is false), yeni sətirlərin tərcümə üçün göndərilməsini təmin etmək məqsədilə gizli read/write API açarından istifadə edəcəyik.

Marşrutlaşdırma və yönləndirmələrin 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 onların üstünlük verdiyi 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ın Next.js Middleware sənədlərinə uyğun olaraq qurulduğundan əmin olun.

Klient tərəfində istifadəçinin üstünlük verdiyi dili dəyişdirmək üçün locale cookie-ni dəyişə bilərsiniz. Bunu necə edəcəyiniz barədə ideyalar üçün tam nümunə koduna baxın!

5-ci addım: Yayımlayın və sınaqdan keçirin!

Hazır oldu! React tətbiqiniz Translate komponentinə hər hansı sətirləri ə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 tərcümə olunacaq yeni sətirləri yarada bilərlər. Belə bir API açarı ilə istehsal tətbiqinizi sınaqdan keçirə və yayıma çıxmazdan əvvəl yeni sətirlər əlavə edə biləcəyiniz bağlanmış və təhlükəsiz bir sınaq (staging) mühitinizin olmasını tövsiyə edirik. Bu, gizli API açarınızı kimsənin oğurlamasının və layihənizə əlaqəsiz yeni sətirlər əlavə edərək onu şişirtməsinin qarşısını alacaq.

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!