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

الخطوة الثانية: قم بإنشاء حساب TacoTranslate مجاني

الآن بعد تثبيت الوحدة، حان الوقت لإنشاء حساب TacoTranslate الخاص بك، ومشروع ترجمة، ومفاتيح API المرتبطة. أنشئ حسابًا هنا. إنه مجاني، ولا يتطلب منك إضافة بطاقة ائتمان.

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

تأكد من عدم تسريب مفتاح واجهة برمجة التطبيقات السري 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!"/>
}

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

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

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

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