أفضل حل للتدويل (i18n) في تطبيقات Next.js

كيف يعمل

مع ازدياد عولمة العالم، أصبح من المهم بشكل متزايد لمطوري الويب بناء تطبيقات قادرة على تلبية احتياجات المستخدمين من دول وثقافات مختلفة. إحدى الطرق الأساسية لتحقيق ذلك هي التدويل (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 بعرض مفتاح واجهة برمجة التطبيقات العام. إذا كنا في بيئة محلية أو اختبارية أو في بيئة المرحلة التجريبية (isProduction is false)، فسنستخدم مفتاح واجهة برمجة التطبيقات السري 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: انشر واختبر!

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

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!