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

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

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

هذا الدليل مخصص لتطبيقات Next.js التي تستخدم Pages Router.
إذا كنت تستخدم App 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: "المجلد" حيث سيتم تخزين نصوصك، مثل عنوان موقع الويب الخاص بك. اقرأ المزيد عن الأصول هنا.

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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

سنقوم بتعريف TACOTRANSLATE_API_KEY تلقائيًا قريبًا.

إن إنشاء العميل في ملف منفصل يجعل من السهل استخدامه مرة أخرى لاحقًا. الآن، باستخدام ملف مخصص /pages/_app.tsx, سنضيف مزود TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

إذا كان لديك بالفعل pageProps و _app.tsx مخصصين، يرجى توسيع التعريف مع الخصائص والكود من الأعلى.

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

يتيح TacoTranslate عرض ترجماتك على جانب الخادم. هذا يحسن تجربة المستخدم بشكل كبير من خلال عرض المحتوى المترجم فورًا، بدلاً من وميض المحتوى غير المترجم أولاً. بالإضافة إلى ذلك، يمكننا تخطي طلبات الشبكة على العميل، لأننا لدينا بالفعل جميع الترجمات التي نحتاجها.

سنبدأ بإنشاء أو تعديل /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

قم بتعديل فحص isProduction ليناسب إعداداتك. إذا كانت true، سيعرض TacoTranslate مفتاح API العام. إذا كنا في بيئة محلية أو اختبارية أو تحضيرية (isProduction is false)، سنستخدم مفتاح API السري read/write لضمان إرسال السلاسل الجديدة للترجمة.

حتى الآن، لقد قمنا فقط بإعداد تطبيق Next.js مع قائمة باللغات المدعومة. الشيء التالي الذي سنفعله هو جلب الترجمات لجميع صفحاتك. للقيام بذلك، ستستخدم إما getTacoTranslateStaticProps أو getTacoTranslateServerSideProps بناءً على متطلباتك.

تأخذ هذه الدوال ثلاث معطيات: كائن واحد من نوع Next.js Static Props Context, تكوين خاص بـ TacoTranslate، وخصائص اختيارية من Next.js. لاحظ أن revalidate في getTacoTranslateStaticProps مضبوط على 60 بشكل افتراضي، بحيث تبقى ترجماتك محدثة.

لاستخدام أي من الدالتين في صفحة، لنفترض أن لديك ملف صفحة مثل /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

يجب أن تكون الآن قادرًا على استخدام مكون Translate لترجمة النصوص داخل جميع مكونات React الخاصة بك.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

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

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

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

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