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

با جهانی‌شدن روزافزون جهان، برای توسعه‌دهندگان وب ساختن برنامه‌هایی که بتوانند به کاربران از کشورهای مختلف و فرهنگ‌های گوناگون خدمت کنند، اهمیت بیشتری یافته است. یکی از راه‌های کلیدی برای رسیدن به این هدف، بین‌المللی‌سازی (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 در ریشه پروژه خود اضافه کنید.

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 وب‌سایت شما. اینجا بیشتر درباره origins بخوانید.

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

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

برای ادغام TacoTranslate با برنامه خود، باید با استفاده از کلیدهای API که قبلاً داشتید یک کلاینت ایجاد کنید. به عنوان مثال، یک فایل به نام /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 را پیاده‌سازی خواهیم کرد.

'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] پارامتر پویا است.

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 ایجاد کنید.

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 را ایجاد یا اصلاح کنید:

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]، می‌توانیم کاربران را به صفحاتی که به زبان مورد علاقه‌شان نمایش داده می‌شود هدایت کنیم.

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 مخفی شما توسط هر کسی جلوگیری خواهد کرد و همچنین امکان پر شدن بی‌رویه پروژه ترجمه شما با رشته‌های جدید و نامرتبط را کاهش می‌دهد.

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!