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.

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çə 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

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

Modulu quraşdırdığınıza görə, indi TacoTranslate hesabınızı, tərcümə layihənizi və müvafiq API açarlarını yaratmağın vaxtıdır. Burada hesab yaradın. 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ı 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ı bizim public adlandırdığımız açardır və read/write açarı isə secret adlandırılı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ə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

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ə avtomatik olaraq TACOTRANSLATE_API_KEY və TACOTRANSLATE_PROJECT_LOCALE təyin ediləcək.

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

Diqqət edin: 'use client'; bunun bir klient 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əli olduğumuz ilk 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əniz üçün 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 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əfli renderi dəstəkləyir. Bu, istifadəçi təcrübəsini xeyli yaxşılaşdırır — tərcümə olunmuş məzmunu dərhal göstərərək əvvəlcə tərcümə olunmamış məzmunun qısa müddətə görünməsinin qarşısını alır. Əlavə olaraq, istifadəçi tərəfdə şəbəkə sorğularını atlaya bilərik, çünki istifadəçinin baxdığı səhifə üçün lazım olan tərcümələr artıq mövcuddur.

Server tərəfli renderi qurmaq üçün /next.config.js-i 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.

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

5-ci addım: Yerləşdirin və sınaqdan keçirin!

Hazırıq! React tətbiqiniz indi hər hansı sətiri Translate komponentinə əlavə etdiyiniz zaman avtomatik olaraq tərcümə olunacaq. Qeyd: API açarı üçün read/write icazəsinə malik olan mühitlər yalnız yeni tərcümə ediləcək sətirləri yarada bilərlər. Belə bir API açarı ilə istehsal tətbiqinizi sınaya biləcəyiniz, yeni sətirləri canlıya çıxmazdan əvvəl əlavə etdiyiniz bağlı və təhlükəsiz bir sınaq mühitinin olması tövsiyə olunur. Bu, heç kimin gizli API açarınızı oğurlamasının və yeni, əlaqəsiz sətirləri əlavə edərək tərcümə layihənizi ş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!