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

Dünya daha da qloballaşdıqca, veb inkişafçıları üçün müxtəlif ölkə 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 əldə etməyin əsas yollarından biri beynəlxalqlaşdırmadır (i18n), bu isə 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əş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 üçün nəzərdə tutulub.
Əgər Pages Router istifadə edirsinizsə, bunun yerinə bu bələdçiyə baxın.

Addım 1: 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çə populyar kitabxana var, o cümlədən next-intl. Lakin bu nümunədə biz TacoTranslate istifadə edəcəyik.

TacoTranslate ən son AI texnologiyasından istifadə edərək sətirlərinizi avtomatik olaraq hər hansı bir dilə tərcümə edir və sizi JSON fayllarının yorucu idarə etməsindən azad edir.

Bunu terminalınızda npm ilə 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ı yaratmağın vaxtıdır. Burada hesab yaradın. Bu pulsuzdur və kredit kartınızı əlavə etməyə ehtiyac yoxdur.

TacoTranslate tətbiqinin UI-sində bir layihə yaradın və onun API keys bölməsinə keçin. Bir read açarı və bir read/write açarı yaradın. Onları ətraf mühit dəyişənləri kimi saxlayacağıq. read açarına biz public deyirik, read/write açarı isə secret adlanır. Məsələn, onları layihənizin kök qovluğunda olan .env faylına əlavə edə bilərsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

Biz həmçinin iki əlavə 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, vebsaytınızın URL-i. Mənbələ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ətbiqinizlə inteqrasiya etmək üçün əvvəlki API açarlarından istifadə edərək 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;

Qısa zamanda avtomatik olaraq TACOTRANSLATE_API_KEY və TACOTRANSLATE_PROJECT_LOCALE təyin olunacaq.

Klienti ayrı faylda yaratmaq onu sonradan yenidən istifadə etməyi asanlaşdırır. getLocales yalnız bəzi daxili səhv emalı olan bir köməkçi funksiyadır. İndi /app/[locale]/tacotranslate.tsx adlı fayl yaradın, burada 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 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 olan ilk məqam odur ki, biz dil üçün tərcümələri çəkmə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 qurmağı və tərcümələrinizi güncəl saxlamağı bildirir.

4-cü addım: Server tərəfdə render etmənin tətbiqi

TacoTranslate server tərəfi renderini dəstəkləyir. Bu, istifadəçi təcrübəsini böyük dərəcədə yaxşılaşdırır, çünki əvvəlcə tərcümə olunmamış məzmunun qısa görüntüsünü göstərmək yerinə, dərhal tərcümə olunmuş məzmunu göstərir. Bundan əlavə, müştəri tərəfdə şəbəkə sorğularını keçə bilərik, çünki istifadəçinin baxdığı səhifə üçün artıq lazım olan tərcümələrə sahibik.

Server tərəfli renderləməyi qurmaq üçün /next.config.js faylını yaradın və ya düzəliş edin:

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ğun dəyişdirin. Əgər true olsa, TacoTranslate açıq API açarını istifadə edəcək. Əgər biz yerli, sınaq və ya staging mühitindəyiksə (isProduction is false), yeni sətirlə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.

Yönləndirmə və istiqamətlə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 şəkildə qurulduğundan əmin olun.

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

5-ci Addım: Yerləşdirin və yoxlayın!

İşimiz bitdi! İndi React tətbiqinizə hər hansı sətir əlavə etdiyiniz zaman o, avtomatik olaraq Translate komponentində tərcümə olunacaq. Qeyd edin ki, yalnız read/write icazələrinə malik API açarı olan mühitlər tərcümə üçün yeni sətirlər yarada biləcək. Tövsiyəmiz budur ki, istehsal tətbiqinizi belə bir API açarı ilə sınaya biləcəyiniz qapalı və təhlükəsiz bir səhnələşdirmə (staging) mühitiniz olsun və canlıya çıxmadan əvvəl yeni sətirlər əlavə edin. Bu, gizli API açarınızın oğurlanmasının qarşısını alacaq və tərcümə layihənizi əlaqəsiz, yeni sətirlər əlavə etməklə ş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!