كيفية تنفيذ التدويل في تطبيق 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: «المجلد» الذي سيتم تخزين سلاسل النص الخاصة بك فيه، مثل عنوان 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_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!"/>
}

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

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

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

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