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

Dünya daha da qloballaşdıqca, veb inkişaf etdiricilər üçün müxtəlif ölkələrdən və mədəniyyətlərdən olan istifadəçilərə uyğun tətbiqlər yaratmaq getdikcə daha vacib olur. Bunun əsas yollarından biri beynəlmiləlləşdirmə (i18n) vasitəsilə tətbiqinizi müxtəlif dillərə, valyutalara və tarix formatlarına uyğunlaşdırmaqdır.

Bu məqalədə, React Next.js tətbiqinizə server tərəfi renderləşdirmə ilə birlikdə beynəlmiləlləşdirmənin necə əlavə olunacağını 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 yerinə 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 istifadə edəcəyik.

TacoTranslate ən son 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 zəhmətli idarəsindən azad edir.

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

npm install tacotranslate

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

İndi modul quraşdırıldığından, 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 İstifadəçi İnterfeysində bir layihə yaradın və API açarları sekmesine 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ını public (ictimai), read/write açarını isə secret (gizli) adlandırırıq. 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

Gizli read/write API açarını müştəri tərəfində istehsal mühitlərinə heç vaxt 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 locale kodu. Bu nümunədə, onu İngilis dili üçün en olaraq təyin edəcəyik.
• TACOTRANSLATE_ORIGIN: Mətnlərinizin saxlanılacağı “qovluq”, məsələn, saytınızın URL-si. 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ından istifadə edərək bir client 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 təyin edəcəyik.

Müştərini ayrıca faylda yaratmaq onu sonra asanlıqla yenidən istifadə etməyə imkan verir. getLocales sadəcə bəzi daxili səhv idarəetməsi ilə bir köməkçi funksiyadır. İndi isə /app/[locale]/tacotranslate.tsx adlı bir 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 'use client'; bunun bir müştəri komponenti olduğunu göstərir.

Kontekst provayderi indi getməyə hazır olduğu üçün, /app/[locale]/layout.tsxadlı fayl yaradın , bizim tətbiqimizdə root layout. Qeyd edək ki, bu cığırda [locale] dinamik parametr olduğu Dynamic Routesistifadə edən qovluq var.

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 nəzərə almaq lazım olan ilk məsələ odur ki, biz dillərin tərcümələrini gətirmək üçün Dynamic Route parametrimiz olan [locale] istifadə edirik. Bundan əlavə, generateStaticParams layihəniz üçün aktivləşdirdiyiniz bütün lokal kodlarının əvvəlcədən renderlənməsini təmin edir.

İndi, gəlin ilk səhifəmizi yaradaq! /app/[locale]/page.tsx adlı 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əldə saxlamasını bildirir.

4-cü Addım: Server tərəfi renderin tətbiqi

TacoTranslate server tərəfində renderi dəstəkləyir. Bu, istifadəçi təcrübəsini xeyli yaxşılaşdırır, çünki tərcümə olunmuş məzmun dərhal göstərilir, əvvəlcə tərcümə olunmamış məzmunun parıltısı yerinə. Əlavə olaraq, müştəri tərəfində şəbəkə sorğularını keçə bilərik, çünki istifadəçinin baxdığı səhifə üçün ehtiyacımız olan tərcümələr artıq mövcuddur.

Server tərəfi renderinqini qurmaq üçün /next.config.js faylını yaradın və ya redaktə 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 quruluşunuza uyğunlaşdırın. Əgər true olarsa, TacoTranslate ümumi API açarını göstərəcək. Əgər biz lokal, test, ya da staging mühitindəsəkk (isProduction is false), yeni sətirlərin tərcüməyə göndərildiyinə əmin olmaq üçün gizli read/write API açarından istifadə edəcəyik.

Yönləndirmənin 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 qurğunu Next.js Middleware sənədlərinə uyğun şəkildə qurduğunuzdan əmin olun.

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

5-ci addım: Yerləşdirin və sınayın!

İşimiz bitdi! İndi React tətbiqinizə hər hansı bir mətn əlavə etdikdə, Translate komponenti vasitəsilə avtomatik tərcümə olunacaq. Qeyd edin ki, yalnız read/write icazələrinə malik API açarı olan mühitlər yeni tərcümə olunacaq mətnlər yarada biləcək. Biz tövsiyə edirik ki, belə bir API açarı ilə istehsal tətbiqinizi sınaqdan keçirə biləcəyiniz, bağlı və təhlükəsiz bir sınaq mühiti (staging environment) olsun; canlı yayıma başlamazdan əvvəl yeni mətnlər əlavə edin. Bu, gizli API açarınızın oğurlanmasının qarşısını alacaq və əlaqəsiz, yeni mətnlərin əlavə olunaraq tərcümə layihənizin şişməsinin qarşısını tutacaq.

Mütləq GitHub profilimizdə tam nümunəyə baxın. Orada, həmçinin bu işi Pages Router istifadə edərək necə etmək barədə nümunə tapa bilərsiniz! Hər hansı problem yaşasanız, bizimlə əlaqə saxlayın, və biz sizə kömək etməkdən məmnun olarıq.

TacoTranslate React tətbiqlərinizi istənilən dildən sürətli və avtomatik olaraq lokallaşdırmağa imkan verir. Bugün başlayın!