چگونه در یک برنامه 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: «پوشه‌ای» که رشته‌های شما در آن ذخیره می‌شوند، مانند آدرس وب‌سایت شما. مطالعه بیشتر درباره مبداء اینجا.

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

برای اطمینان از اینکه مسیر یابی و هدایت مجدّد طبق انتظار عمل می‌کند، نیاز داریم فایلی به نام /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 را مطابق با مستندات میان‌افزار Next.js تنظیم کرده‌اید.

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

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

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

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

تاکوترنسلیت به شما امکان می‌دهد برنامه‌های React خود را به سرعت و به صورت خودکار به هر زبانی ترجمه کنید. امروز شروع کنید!