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

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 الخاصة بك تلقائيًا بسرعة من وإلى أي لغة. ابدأ اليوم!