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

تأكد من عدم تسريب مفتاح واجهة برمجة التطبيقات السري read/write إلى بيئات الإنتاج على جانب العميل.

سنضيف أيضًا متغيرين آخرين للبيئة: TACOTRANSLATE_DEFAULT_LOCALE و TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: رمز اللغة الافتراضية الاحتياطية. في هذا المثال، سنضبطه على en للغة الإنجليزية.
• TACOTRANSLATE_ORIGIN: الـ“folder” حيث سيتم تخزين سلاسل النص الخاصة بك، مثل عنوان 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 من هذا النوع، وإضافة سلاسل جديدة قبل الإطلاق. سيمنع ذلك أي شخص أي شخص من سرقة المفتاح السري لواجهة برمجة التطبيقات الخاص بك، وقد يؤدي أيضًا إلى تضخيم مشروع الترجمة الخاص بك عن طريق إضافة سلاسل جديدة غير ذات صلة.

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

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