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

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

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

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

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