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

Dünya daha da qloballaşdıqca, veb tərtibatçıları üçün müxtəlif ölkələrdən 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 ə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əfində render etmə ilə beynəlmiləlləşdirməni necə əlavə etməyi 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 siz Pages Router istifadə edirsinizsə, bunun 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 mövcuddur, o cümlədən next-intl. Lakin bu nümunədə biz TacoTranslate 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.

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

npm install tacotranslate

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

İndi modul qurulduğuna görə, TacoTranslate hesabınızı, tərcümə layihənizi və əlaqəli API açarlarını yaratmağın vaxtıdır. Buradan hesab yaradın. Bu pulsuzdur və kredit kartı əlavə etməyinizi tələb etmir.

TacoTranslate tətbiq interfeysində 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ına public deyirik, read/write açarı isə secret adlanı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

Müştəri tərəfindəki istehsal mühitlərinə heç vaxt gizli read/write API açarını sızdırmamağa diqqət edin.

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 dil kodu. Bu nümunədə bunu İngilis dili üçün en kimi təyin edəcəyik.
• TACOTRANSLATE_ORIGIN: Sətirlərinizin saxlanılacağı “qovluq”, məsələn, domeninizin URL-i. Burada origins haqqında daha çox 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əlcə 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 sonradan yenidən istifadə etməyi asanlaşdırır. getLocales isə bəzi daxili səhv idarəetməsi olan yardımçı funksiyadır. İndi /app/[locale]/tacotranslate.tsx adlı bir fayl yaradın, burada TacoTranslate təminatçısını 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'; bu komponentin client komponenti olduğunu göstərir.

Kontekst təminatçısı hazır olduqdan sonra /app/[locale]/layout.tsx adlı fayl yaradın, bu, tətbiqimizdə əsas layout-dur. Qeyd edin ki, bu yol Dynamic Routes istifadə edən bir qovluqa 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 ilk qeyd etmək lazım olan odur ki, biz tərcümələri həmin dil üçün əldə etmək üçün Dynamic Route parametri [locale] istifadə edirik. Bundan əlavə, generateStaticParams layihəniz üçün aktivləşdirdiyiniz bütün lokal 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əldə saxlamağı bildirir.

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

TacoTranslate server tərəfi renderini dəstəkləyir. Bu, istifadəçi təcrübəsini xeyli yaxşılaşdırır, çünki əvvəlcə tərcümə olunmamış məzmunun anlıq görünməsi əvəzinə, dərhal tərcümə olunmuş məzmun göstərilir. Üstəlik, müştəri tərəfində şəbəkə sorğularını keçə bilərik, çünki istifadəçinin baxdığı səhifəyə lazım olan tərcümələr artıq mövcuddur.

Server tərəfli renderləşdirmə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};
};

isProduction yoxlamasını öz mühitinizə uyğunlaşdırın. Əgər true olarsa, TacoTranslate ictimai API açarını göstərəcək. Əgər biz yerli, test və ya staging mühitindəyiksə (isProduction is false), yeni sətirlərin tərcümə üçün göndərildiyinə əmin olmaq üçün gizli read/write API açarından istifadə edəcəyik.

Yönləndirmə və keçidlə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 ü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 -i Next.js Middleware sənədlərinə uyğun olaraq qurduğunuzdan əmin olun.

Müştəri tərəfində, istifadəçinin üstünlük verdiyi dili dəyişdirmə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: Yayım edin və test edin!

Biz işimizi bitirdik! İndi sizin React tətbiqiniz avtomatik olaraq tərcümə olunacaq, nə vaxt ki, Translate komponentinə hər hansı sətirlər əlavə edərsiniz. Qeyd edin ki, yalnız API açarında read/write icazələri olan mühitlər yeni tərcümə olunacaq sətirləri yarada biləcəklər. Biz tövsiyə edirik ki, belə bir API açarı ilə istehsalat tətbiqinizi sınaya biləcəyiniz bağlı və təhlükəsiz bir staging mühiti saxlayasınız, canlı yayıma başlamazdan əvvəl yeni sətirlər əlavə edəsiniz. Bu, hər kəsin gizli API açarınızı oğurlamasının qarşısını alacaq və potensial olaraq tərcümə layihənizi əlaqəsiz yeni sətirlər əlavə edərək şişirtməsinin qarşısını alacaq.

Əmin olun ki, tam nümunəyə GitHub profilimizdə baxasınız. Orada Pages Router istifadə edərək bunu necə edəcəyinizə dair bir nümunə də tapacaqsınız! Hər hansı bir problem yaşasanız, bizimlə əlaqə saxlayın, və biz sizə kömək etməkdən məmnun olarıq.

TacoTranslate sizə React tətbiqlərinizi istənilən dilə avtomatik olaraq tez bir zamanda lokalizasiya etməyə imkan verir. Bu gün başlayın!