Next.js tətbiqlərində beynəlxalqlaşdırma (i18n) üçün ən yaxşı həll

Necə işləyir

Dünya daha qloballaşdıqca, veb inkişaf etdiricilər üçü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 vacibdir. 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 dərslikdə biz React Next.js tətbiqinizə server tərəfdən renderlə necə beynəlxalqlaşdırma əlavə etməyi araşdıracağıq. TL;DR: Tam nümunəni burada görün.

Bu bələdçi Pages Router istifadə edən Next.js tətbiqləri üçündür.
Əgər App Router istifadə edirsinizsə, onun əvəzinə bu bələdçiyə baxın.

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

Next.js tətbiqinizdə beynəlxalqləşdirməni (i18n) həyata keçirmək üçün əvvəlcə bir i18n kitabxanası seçməliyik. Bir neçə populyar kitabxana var, o cümlədən next-intl. Bununla belə, bu nümunədə TacoTranslate istifadə edəcəyik.

TacoTranslate qabaqcıl süni intellektdən istifadə edərək mətnlə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 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ız üçün indi TacoTranslate hesabı, tərcümə layihəsi və əlaqəli API açarlarını yaratmağın zamanı gəldi. Buradan 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ə API açarları sekməsinə 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ını biz public adlandırırıq, 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

Gizli read/write API açarını heç vaxt müştəri tərəfli istehsal mühitlərinə sızdırmadığınızdan əmin olun.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan ehtiyat (fallback) lokal kodu. Bu nümunədə onu İngilis dili üçün en olaraq təyin edəcəyik.
• TACOTRANSLATE_ORIGIN: Sətirlərinizin saxlanacağı “qovluq”, məsələn saytınızın URL-i. Orijinlər haqqında daha çox məlumatı burada oxuyun.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

3-cü addım: TacoTranslate-in quraşdırılması

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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Biz tezliklə avtomatik olaraq TACOTRANSLATE_API_KEY təyin edəcəyik.

Klienti ayrı bir faylda yaratmaq onu daha sonra yenidən istifadə etməyi asanlaşdırır. İndi isə xüsusi /pages/_app.tsx istifadə edərək, TacoTranslate provayderini əlavə edəcəyik.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Əgər artıq öz pageProps və _app.tsx fayllarınız varsa, zəhmət olmasa tərifi yuxarıdakı xüsusiyyətlər və kod ilə genişləndirin.

Addım 4: Server tərəfində renderləməni həyata keçirmək

TacoTranslate tərcümələrinizin server tərəfdən render edilməsinə imkan verir. Bu, istifadəçi təcrübəsini xeyli yaxşılaşdırır — əvvəlcə tərcümə olunmamış məzmunun qısa görünüşü (flash) əvəzinə tərcümə edilmiş məzmunu dərhal göstərir. Bundan əlavə, lazım olan bütün tərcümələr artıq mövcud olduğundan, klientdə şəbəkə sorğularını keçə bilərik.

Biz /next.config.js faylını yaradaraq və ya dəyişdirərək başlayacağıq.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

isProduction yoxlamasını quruluşunuza 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ə olsaq (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.

İndiyə qədər Next.js tətbiqini yalnız dəstəklənən dillərin siyahısı ilə qurmuşuq. Növbəti edəcəyimiz şey bütün səhifələriniz üçün tərcümələri əldə etməkdir. Bunun üçün tələblərinizə əsasən ya getTacoTranslateStaticProps, ya da getTacoTranslateServerSideProps istifadə edəcəksiniz.

Bu funksiyalar üç arqument qəbul edir: biri Next.js Static Props Context obyekti, TacoTranslate üçün konfiqurasiya və istəyə bağlı Next.js xüsusiyyətləri. Qeyd edin ki, getTacoTranslateStaticProps üzərində revalidate varsayılan olaraq 60-a təyin edilib, beləliklə tərcümələriniz güncəl qalır.

Hər hansı bir funksiyanı səhifədə istifadə etmək üçün fərz edək ki, sizin /pages/hello-world.tsx kimi bir səhifə faylınız var.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

İndi Translate komponentindən istifadə edərək bütün React komponentlərinizdəki mətnləri tərcümə edə bilməlisiniz.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

5-ci addım: Yayımlayın və test edin!

Bitirdik! Next.js tətbiqiniz indi Translate komponentinə hər hansı sətir əlavə etdikdə avtomatik olaraq tərcümə olunacaq. Qeyd edin ki, yalnız API açarında read/write icazəsi olan mühitlər yeni tərcümə olunacaq sətirləri yarada biləcək. Belə bir API açarı ilə istehsal tətbiqinizi sınaqdan keçirmək və canlı yayımlamadan əvvəl yeni sətirlər əlavə etmək üçün qapalı və təhlükəsiz bir staging mühiti olmasını tövsiyə edirik. Bu, kimsənin gizli API açarınızı oğurlamasının və tərcümə layihənizi əlaqəsiz yeni sətirlərlə ş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 App 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!