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

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 را مطابق با مستندات میان‌افزار 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!