Next.js tətbiqində App Router istifadə edilən halda beynəlxalqlaşdırmanı (i18n) necə tətbiq etmək olar?

Dünya daha da qloballaşdıqca, veb tərtibatçılar üçün müxtəlif ölkə və mədəniyyətlərdən olan istifadəçilərə uyğunlaşa bilən tətbiqlər yaratmaq getdikcə daha vacib olur. Bunun əldə edilməsinin əsas yollarından biri beynəlxalqlaşdırmadır (i18n), 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əf renderləşməsi ilə necə beynəlxalqlaşdırma əlavə etməyi araşdıracağıq. TL;DR: Tam nümunəni buradan görün.

Bu bələdçi App Router istifadə edən Next.js tətbiqləri üçündür.
Əgər Pages Router istifadə edirsinizsə, bunun ə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 var, o cümlədən next-intl. Lakin bu nümunədə biz TacoTranslate-dən istifadə edəcəyik.

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

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

npm install tacotranslate

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

Modulu artıq quraşdırdığınıza görə, indi TacoTranslate hesabınızı, tərcümə layihənizi və əlaqəli API açarlarını yaratmağın vaxtıdır. Buradan 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ə API açarları nişanı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ı bizim public adlandırdığımız açardır, read/write açarı isə secret adlandırdığımız açardır. Məsələn, onları layihənizin kök qovluğunda yerləşən .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əfi istehsal mühitlərinə 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: Varsayılan ehtiyat lokal 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

3-cü addım: 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;

Biz qısa müddət ərzində avtomatik olaraq TACOTRANSLATE_API_KEY və TACOTRANSLATE_PROJECT_LOCALE təyin edəcəyik.

Klienti ayrı faylda yaratmaq onu sonra yenidən istifadə etməyi asanlaşdırır. getLocales sadəcə daxili səhv idarəetməsi olan bir yardımçı 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>
	);
}

Qeyd edin ki, 'use client'; bu bir client komponenti olduğunu göstərir.

Kontekst provayderi artıq istifadəyə hazır olduğuna görə, tətbiqimizdə kök layout olan /app/[locale]/layout.tsx adlı bir fayl yaradın. Qeyd edək ki, bu yol Dynamic Routes istifadə edən bir qovluğa malikdir, 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 etmək lazımdır ki, biz həmin dil üçün tərcümələri əldə etmək üçün Dynamic Route parametrimiz [locale] istifadə edirik. Əlavə olaraq, generateStaticParams layihəniz üçün aktiv etdiyiniz bütün locale kodlarının öncədən render olunmasını təmin edir.

İndi gəlin ilk səhifəmizi yaradaq! /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-ə səhifəni 60 saniyədən sonra yenidən qurmağı və tərcümələrinizi güncəl saxlamasını bildirən revalidate dəyişəninə diqqət edin.

Addım 4: Server tərəfində renderləməni həyata keçirmək

TacoTranslate server tərəfdən renderləməni dəstəkləyir. Bu, istifadəçi təcrübəsini əhəmiyyətli dərəcədə yaxşılaşdırır — əvvəlcə tərcümə olunmamış məzmunun parıltısı yerinə tərcümə olunmuş məzmunu dərhal göstərir. Bundan əlavə, istifadəçinin baxdığı səhifə üçün lazım olan tərcümələrimiz artıq olduğundan, müştəri tərəfdə şəbəkə sorğularını atlaya bilərik.

Server tərəfli renderləmə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};
};

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

Marşrutlaşdırma 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 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);
}

matcheri Next.js Middleware sənədlərinə uyğun olaraq qurduğunuzdan əmin olun.

Müştəri tərəfində, istifadəçinin üstünlük verdiyi dili dəyişdirmək üçün locale kukisini dəyişdirə bilərsiniz. Bunun necə ediləcəyinə dair ideyalar üçün tam nümunə koduna baxın!

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

Tamamladıq! React tətbiqiniz indi Translate komponentinə hər hansı sətir əlavə etdiyiniz zaman avtomatik olaraq tərcümə ediləcək. Qeyd edin ki, yalnız API açarında read/write icazələri olan mühitlər tərcümə üçün yeni sətirlər yarada biləcəklər. Belə bir API açarı ilə istehsal tətbiqinizi test edə biləcəyiniz, yeni sətirləri canlıya çıxmadan əvvəl əlavə edə biləcəyiniz bağlı və təhlükəsiz bir sınaq mühiti qurmağı tövsiyə edirik. Bu, gizli API açarınızı kimsənin oğurlamasının və eyni zamanda yeni, əlaqəsiz sətirlər əlavə etməklə tərcümə layihənizin şişməsi riskinin 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!