App Router istifadə edən Next.js tətbiqində çoxdilliliyi (i18n) necə tətbiq etmək olar App Router

Dünya daha da qloballaşdıqca, veb inkişaf etdiricilər üçün müxtəlif ölkə və mədəniyyətlərdən olan istifadəçilərə xidmət edə biləcək tətbiqlər yaratmaq getdikcə daha vacib olur. Buna nail olmağın əsas yollarından biri internacionalizasiya (i18n)dir, 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ə server tərəfdən renderləmə ilə React Next.js tətbiqinizə internacionalizasiya necə əlavə etməyi araşdıracağıq. TL;DR: Tam nümunəni burada görə bilərsiniz.

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ı 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. Bu nümunədə isə biz TacoTranslate-dən istifadə edəcəyik.

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

Gəlin bunu terminalınızda npm ilə quraşdıraq:

npm install tacotranslate

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

Modulu qurduğunuz üçün indi 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ı əlavə etməyinizi tələb etmir.

TacoTranslate tətbiqinin istifadəçi interfeysində bir layihə yaradın və API açarları sekmə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, read/write açarı isə secret adlanır. 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ı heç vaxt müştəri tərəfi istehsal mühitlərinə sızdırmayın.

Bununla yanaşı iki mühit dəyişəni daha əlavə edəcəyik: TACOTRANSLATE_DEFAULT_LOCALE və TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan ehtiyat (fallback) locale kodudur. 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 qurulması

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 sonradan yenidən istifadə etməyi asanlaşdırır. getLocales sadəcə bəzi daxili səhv emalı 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>
	);
}

Komponentin müştəri komponenti olduğunu göstərən 'use client'; ifadəsinə diqqət edin.

Kontekst provayderi indi hazır olduğuna görə, tətbiqimizdə əsas layout olan /app/[locale]/layout.tsx adlı faylı yaradın. Qeyd edin 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, müəyyən dil üçün tərcümələri əldə etmək üçün Dynamic Route parametrimiz [locale] istifadə olunur. Əlavə olaraq, generateStaticParams layihəniz üçün aktiv etdiyiniz bütün lokal kodlarının əvvəlcədən render olunduğuna əmin olur.

İndi gəlin ilk səhifəmizi quraq! /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!" />
	);
}

Səhifəni 60 saniyədən sonra Next.js-in yenidən qurmasını və tərcümələrinizi güncəldə saxlamasını bildirən revalidate dəyişəninə diqqət edin.

Step 4: Server-tərəfli renderləmənin tətbiqi

TacoTranslate server tərəfli renderi dəstəkləyir. Bu, tərcümə olunmuş məzmunu əvvəlcə qısa müddətli tərcüməsiz məzmunun görünməsi əvəzinə dərhal göstərməklə istifadəçi təcrübəsini əhəmiyyətli dərəcədə yaxşılaşdırır. Bundan əlavə, istifadəçinin baxdığı səhifə üçün lazım olan tərcümələr artıq mövcud olduğuna görə, müştəri tərəfində şəbəkə sorğularını atlayırıq.

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

Quraşdırmanı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 yerli, test 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.

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 seçdiyi dildə göstərilən 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 parametrini Next.js Middleware sənədlərinə uyğun şəkildə qurduğunuzdan əmin olun.

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

Addım 5: Yerləşdirin və sınaqdan keçirin!

Hazırıq! React tətbiqiniz indi Translate komponentinə hər hansı sətirlər əlavə etdiyiniz zaman avtomatik olaraq tərcümə olunacaq. Qeyd edin ki, API açarı üçün read/write icazəsi olan mühitlər yalnız tərcümə üçün yeni sətirlər yarada bilərlər. Biz tövsiyə edirik ki, belə bir API açarı ilə istehsal tətbiqinizi sınaqdan keçirə biləcəyiniz və yeni sətirləri canlıya çıxmadan əvvəl əlavə edə biləcəyiniz bağlı və təhlükəsiz bir staging mühiti yaradəsiniz. Bu, gizli API açarınızın oğurlanmasının və yeni, əlaqəsiz sətirlərin əlavə edilməsi ilə tərcümə layihənizin şişmə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!