Next.js tətbiqində, App Router istifadə edildikdə, beynəlxalqlaşdırmanı necə tətbiq etmək olar

Aləmdə getdikcə qloballaşma artdıqca, veb inkişaf etdiricilərin müxtəlif ölkə və mədəniyyətlərdən olan istifadəçilərə uyğunlaşa bilən tətbiqlər yaratmaları daha vacib olur. Bunu əldə etməyin əsas yollarından biri beynəlxalqlaşdırma (i18n)-dır; bu, 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əmə ilə beynəlxalqlaşdırmanı necə əlavə edəcəyimizi 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 əvəzinə bu bələdçiyə baxın.

Addım 1: i18n kitabxanasını quraşdırın

Next.js tətbiqinizdə beynəlmiləlləşdirməni (i18n) tətbiq etmə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 ən müasir 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 yorucu idarə edilməsindən azad edir.

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

npm install tacotranslate

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

Modulu quraşdırdığınıza görə indi TacoTranslate hesabınızı, tərcümə layihənizi və əlaqəli API açarlarını yaratmaq vaxtıdır. Buradan hesab yaradın. Bu pulsuzdur və kredit kartı əlavə etməyinizi tələb etmir.

TacoTranslate tətbiqinin UI-də bir layihə yaradın və onun API açarları sekmesine 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, və read/write açarı isə secret. 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əfdəki istehsal mühitlərinə heç vaxt sızdırmadığınızdan əmin olun.

Həmçinin iki əlavə mühit dəyişəni əlavə edəcəyik: TACOTRANSLATE_DEFAULT_LOCALE və TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan ehtiyat locale 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ı 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ə TACOTRANSLATE_API_KEY və TACOTRANSLATE_PROJECT_LOCALE avtomatik olaraq təyin ediləcək.

Müştərini ayrı bir faylda yaratmaq onu daha sonra yenidən istifadə etməyi asanlaşdırır. getLocales sadəcə bəzi daxili səhv idarəetməsi 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>
	);
}

Qeyd edin ki, 'use client'; bunun bir müştəri komponenti olduğunu göstərir.

Kontekst təminatçısı indi hazır olduqdan sonra, tətbiqimizdə əsas layout olan /app/[locale]/layout.tsx adlı bir fayl yaradın. Qeyd edin ki, bu yol Dynamic Routes-dan istifadə edən bir qovluğa malikdir və 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 nəzərə alınmalı ilk məqam odur 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 renderlənməsini təmin edir.

İndi gəlin ilk səhifəmizi quraq! /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ə sonra yenidən qurmağı və tərcümələrinizi güncəldə saxlamağı tapşırır.

4-cü addım: Server tərəfli renderləmənin tətbiqi

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ərir və beləliklə əvvəlcə tərcümə olunmamış məzmunun qısa müddət görünməsinin qarşısını alır. Əlavə olaraq, müştəri 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əfində 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};
};

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

Marşrutlaşdırma və yönləndirmələrin 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);
}

matcherın Next.js Middleware sənədlərinə uyğun olaraq qurulduğundan əmin olun.

Klient tərəfdə istifadəçinin üstünlük verdiyi dili dəyişdirmək üçün locale kukisini dəyişə bilərsiniz. Bunu necə edəcəyiniz barədə ideyalar üçün tam nümunə koduna baxın!

Addım 5: Yayımlayın və sınaqdan keçirin!

Tamamladıq! React tətbiqiniz indi Translate komponentinə istənilən sətri əlavə etdiyiniz zaman avtomatik olaraq tərcümə olunacaq. Qeyd edək ki, yalnız API açarında read/write icazəsinə malik olan mühitlər tərcümə olunacaq yeni sətirləri yarada biləcəklər. İstehsal tətbiqinizi belə bir API açarı ilə canlıya çıxmazdan əvvəl yeni sətirləri əlavə edib sınaqdan keçirə biləcəyiniz bağlanmış və təhlükəsiz bir hazırlıq (staging) mühiti olmasını tövsiyə edirik. Bu, heç kimin heç kimin gizli API açarınızı oğurlamasının və potensial olaraq tərcümə layihənizi yeni, əlaqəsiz sətirlərin əlavə olunması ilə ş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!