چگونه در یک برنامه Next.js که از App Router استفاده می‌کند، بین‌المللی‌سازی را پیاده‌سازی کنیم

اپلیکیشن React خود را با بین‌المللی‌سازی (i18n) قابل دسترس‌تر کنید و به بازارهای جدید دست یابید.

همزمان با جهانی شدن روزافزون، برای توسعه‌دهندگان وب اهمیت بیشتری پیدا می‌کند که برنامه‌هایی بسازند که بتوانند نیازهای کاربران از کشورهای مختلف و فرهنگ‌های گوناگون را تأمین کنند. یکی از راه‌های کلیدی برای رسیدن به این هدف، بین‌المللی‌سازی (i18n) است که به شما اجازه می‌دهد برنامه‌تان را به زبان‌ها، ارزها و فرمت‌های تاریخ مختلف تطبیق دهید.

در این مقاله، نحوه افزودن بین‌المللی‌سازی به برنامه React Next.js خود با رندر سمت سرور را بررسی خواهیم کرد. TL;DR: نمونه کامل را اینجا ببینید.

این راهنما برای برنامه‌های Next.js است که از App Router استفاده می‌کنند.
اگر شما از Pages Router استفاده می‌کنید، به جای آن این راهنما را ببینید.

مرحله ۱: نصب یک کتابخانه i18n

برای پیاده‌سازی بین‌المللی‌سازی در برنامه Next.js خود، ابتدا یک کتابخانه i18n انتخاب خواهیم کرد. چندین کتابخانه معروف وجود دارد، از جمله next-intl. با این حال، در این مثال، ما از TacoTranslate استفاده خواهیم کرد.

TacoTranslate رشته‌های شما را به‌طور خودکار به هر زبانی با استفاده از هوش مصنوعی پیشرفته ترجمه می‌کند و شما را از مدیریت خسته‌کننده فایل‌های JSON آزاد می‌سازد.

بیایید آن را با استفاده از npm در ترمینال خود نصب کنیم:

npm install tacotranslate

مرحله ۲: یک حساب کاربری رایگان در TacoTranslate ایجاد کنید

اکنون که ماژول را نصب کرده‌اید، وقت آن است که حساب کاربری TacoTranslate خود را ایجاد کنید، یک پروژه ترجمه بسازید و کلیدهای API مربوطه را دریافت نمایید. اینجا حساب کاربری ایجاد کنید. این کار رایگان است و نیازی به وارد کردن کارت اعتباری ندارد.

در داخل رابط کاربری برنامه TacoTranslate، یک پروژه ایجاد کنید و به تب کلیدهای API آن بروید. یک کلید read و یک کلید read/write بسازید. ما آنها را به عنوان متغیرهای محیطی ذخیره خواهیم کرد. کلید read چیزی است که ما آن را public می‌نامیم و کلید read/write کلید secret است. برای مثال، می‌توانید آنها را به یک فایل .env در ریشه پروژه خود اضافه کنید.

.env

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

حتماً هرگز کلید API مخفی read/write را به محیط‌های تولید سمت مشتری ندهید.

ما همچنان دو متغیر محیطی دیگر اضافه خواهیم کرد: TACOTRANSLATE_DEFAULT_LOCALE و TACOTRANSLATE_ORIGIN.

TACOTRANSLATE_DEFAULT_LOCALE: کد پیش‌فرض زبان پشتیبان. در این مثال، ما آن را روی en برای زبان انگلیسی تنظیم خواهیم کرد.
TACOTRANSLATE_ORIGIN: «پوشه» ای که رشته‌های شما در آن نگهداری خواهد شد، مانند آدرس URL سایت شما. برای خواندن بیشتر درباره مبداها اینجا کلیک کنید.

.env

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

مرحله ۳: راه‌اندازی TacoTranslate

برای ادغام TacoTranslate با برنامه‌ی خود، نیاز است که یک کلاینت با استفاده از کلیدهای API که قبلاً ایجاد کرده‌اید بسازید. برای مثال، یک فایل به نام /tacotranslate-client.js ایجاد کنید.

/tacotranslate-client.js

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;

ما به‌طور خودکار TACOTRANSLATE_API_KEY و TACOTRANSLATE_PROJECT_LOCALE را به‌زودی تعریف خواهیم کرد.

ایجاد کلاینت در یک فایل جداگانه باعث می‌شود که بعداً بتوان به‌راحتی دوباره از آن استفاده کرد. getLocales تنها یک تابع کمکی است که دارای برخی از مدیریت خطاهای داخلی می‌باشد. حالا، یک فایل با نام /app/[locale]/tacotranslate.tsx بسازید، جایی که ما ارائه‌دهنده TacoTranslate را پیاده‌سازی خواهیم کرد.

/app/[locale]/tacotranslate.tsx

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

توجه کنید به 'use client'; که نشان می‌دهد این یک مؤلفه کلاینت است.

با آماده شدن فراهم‌کننده‌ی زمینه، یک فایل به نام /app/[locale]/layout.tsx ایجاد کنید، که طرح ریشه‌ای در برنامه‌ی ما است. توجه داشته باشید که این مسیر دارای یک پوشه است که از Dynamic Routes استفاده می‌کند، جایی که [locale] پارامتر پویا است.

/app/[locale]/layout.tsx

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

اولین موردی که باید توجه کنید این است که ما از پارامتر Dynamic Route خود [locale] برای گرفتن ترجمه‌ها به زبان مورد نظر استفاده می‌کنیم. علاوه بر این، generateStaticParams اطمینان حاصل می‌کند که تمام کدهای محلی که برای پروژه خود فعال کرده‌اید، پیش‌نمایش شده‌اند.

حالا بیایید اولین صفحه خود را بسازیم! یک فایل با نام /app/[locale]/page.tsx ایجاد کنید.

/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!" />
	);
}

به متغیر revalidate توجه کنید که به Next.js می‌گوید صفحه را پس از ۶۰ ثانیه دوباره بسازد و ترجمه‌های شما را به‌روز نگه دارد.

مرحله ۴: پیاده‌سازی رندرینگ سمت سرور

TacoTranslate از رندر سمت سرور پشتیبانی می‌کند. این امر تجربه کاربری را به طور قابل توجهی بهبود می‌بخشد زیرا محتویات ترجمه‌شده را فوراً نمایش می‌دهد، به جای اینکه اول محتوای ترجمه‌نشده را به نمایش بگذارد. همچنین، ما می‌توانیم درخواست‌های شبکه‌ای را در سمت کلاینت رد کنیم، زیرا ترجمه‌های مورد نیاز برای صفحه‌ای که کاربر مشاهده می‌کند را از پیش داریم.

برای راه‌اندازی رندر سمت سرور، فایل /next.config.js را ایجاد یا ویرایش کنید:

/next.config.js

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 را مطابق با محیط خود تغییر دهید. اگر true باشد، TacoTranslate کلید عمومی API را نشان خواهد داد. اگر ما در یک محیط محلی، آزمایشی یا staging باشیم (isProduction is false)، از کلید مخفی read/write API استفاده خواهیم کرد تا مطمئن شویم رشته‌های جدید برای ترجمه ارسال می‌شوند.

برای اطمینان از اینکه مسیردهی و تغییر مسیر همان‌گونه که انتظار می‌رود عمل می‌کند، باید فایلی به نام /middleware.ts ایجاد کنیم. با استفاده از Middleware, می‌توانیم کاربران را به صفحاتی که به زبان مورد علاقه‌شان ارائه شده‌اند هدایت کنیم.

/middleware.ts

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 را مطابق با مستندات Middleware در Next.js تنظیم کرده‌اید.

در سمت کلاینت، شما می‌توانید کوکی locale را تغییر دهید تا زبان مورد علاقهٔ کاربر را تنظیم کنید. لطفاً برای دریافت ایده‌هایی در مورد چگونگی انجام این کار، به کد نمونه کامل مراجعه کنید!

مرحله ۵: استقرار دهید و آزمایش کنید!

ما کار را به پایان رساندیم! حالا برنامه React شما به صورت خودکار ترجمه خواهد شد هرگاه که هر رشته‌ای را به یک کامپوننت Translate اضافه کنید. توجه داشته باشید که فقط محیط‌هایی که مجوز read/write بر روی کلید API دارند قادر خواهند بود رشته‌های جدیدی برای ترجمه ایجاد کنند. ما توصیه می‌کنیم یک محیط تست بسته و امن داشته باشید که بتوانید برنامه تولید خود را با چنین کلید API ای آزمایش کنید، و قبل از راه‌اندازی رشته‌های جدید اضافه کنید. این کار از دزدی کلید API محرمانه شما توسط هر کسی جلوگیری می‌کند و همچنین از اضافه شدن رشته‌های نامرتبط که باعث افزایش غیرضروری پروژه ترجمه شما می‌شود، پیشگیری خواهد کرد.

حتما نمونه کامل را در پروفایل گیت‌هاب ما ببینید. آنجا، همچنین یک نمونه خواهید یافت از اینکه چگونه این کار را با استفاده از Pages Router انجام دهید! اگر با مشکلی مواجه شدید، بدون تردید تماس بگیرید، و ما با کمال میل آماده کمک هستیم.

TacoTranslate به شما امکان می‌دهد تا برنامه‌های React خود را به‌طور خودکار به سرعت به هر زبانی و از هر زبان دیگری محلی‌سازی کنید. امروز شروع کنید!