كيفية تنفيذ التدويل في تطبيق Next.js يستخدم App Router

مع تزايد عولمة العالم، أصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات تلبي احتياجات المستخدمين من دول وثقافات مختلفة. واحدة من الطرق الرئيسية لتحقيق ذلك هي من خلال التعريب (i18n)، الذي يتيح لك تكييف تطبيقك مع لغات مختلفة، وعُملات، وصيغ تواريخ متنوعة.

في هذا المقال، سوف نستعرض كيفية إضافة التعريب إلى تطبيقك المبني باستخدام React و Next.js، مع دعم العرض من جانب الخادم. TL;DR: انظر المثال الكامل هنا.

هذا الدليل مخصص لتطبيقات Next.js التي تستخدم App Router.
إذا كنت تستخدم Pages Router, يرجى الاطلاع على هذا الدليل بدلاً من ذلك.

الخطوة 1: تثبيت مكتبة i18n

لتنفيذ التدويل في تطبيق Next.js الخاص بك، سنبدأ أولاً باختيار مكتبة i18n. هناك العديد من المكتبات الشهيرة، بما في ذلك next-intl. في هذا المثال، مع ذلك، سنستخدم TacoTranslate.

يقوم TacoTranslate بترجمة النصوص الخاصة بك تلقائيًا إلى أي لغة باستخدام تقنية الذكاء الاصطناعي المتطورة، ويحررك من إدارة ملفات JSON المملة.

لِنقم بتثبيته باستخدام npm في الطرفية الخاصة بك:

npm install tacotranslate

الخطوة 2: إنشاء حساب مجاني على 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

الخطوة 3: إعداد 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 بإعادة بناء الصفحة بعد 60 ثانية، والحفاظ على تحديث ترجماتك.

الخطوة 4: تنفيذ العرض من جانب الخادم

يدعم 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 العام. إذا كنا في بيئة محلية أو اختبار أو مرحلة تجريبية (isProduction is false)، سنستخدم مفتاح API السري read/write للتأكد من إرسال السلاسل الجديدة للترجمة.

لضمان أن يعمل التوجيه وإعادة التوجيه كما هو متوقع، سنحتاج إلى إنشاء ملف باسم /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 لتغيير اللغة المفضلة للمستخدم. يرجى الاطلاع على الكود الكامل للمثال للحصول على أفكار حول كيفية القيام بذلك!

الخطوة 5: نشر واختبار!

لقد انتهينا! سيتم الآن ترجمة تطبيق React الخاص بك تلقائيًا عند إضافة أي نصوص إلى مكون Translate. لاحظ أن البيئات التي تمتلك أذونات read/write على مفتاح API فقط هي التي ستتمكن من إنشاء نصوص جديدة للترجمة. نوصي بالحفاظ على بيئة اختبار مغلقة وآمنة حيث يمكنك اختبار تطبيق الإنتاج الخاص بك باستخدام مفتاح API من هذا النوع، وإضافة نصوص جديدة قبل النشر المباشر. هذا سيمنع أي شخص من سرقة مفتاح API السري الخاص بك، ومن المحتمل أن يمنع تضخم مشروع الترجمة الخاص بك بإضافة نصوص جديدة غير ذات صلة.

تأكد من مراجعة المثال الكامل على ملفنا الشخصي في GitHub. هناك، ستجد أيضًا مثالًا على كيفية القيام بذلك باستخدام Pages Router ! إذا واجهت أي مشاكل، لا تتردد في الاتصال بنا، وسنكون سعداء بمساعدتك.

يتيح لك TacoTranslate تعريب تطبيقات React الخاصة بك تلقائيًا بسرعة من وإلى أي لغة. ابدأ اليوم!