كيفية تنفيذ التعريب في تطبيق 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

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 مفتاح واجهة برمجة التطبيقات العام. إذا كنا في بيئة محلية أو تجريبية أو مرحلية (isProduction is false)، فسنستخدم مفتاح واجهة برمجة تطبيقات 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 الخاصة بك تلقائيًا بسرعة من وإلى أي لغة. ابدأ اليوم!