أفضل حل للتدويل (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 مخصصان، يرجى توسيع التعريف بالخصائص والكود من الأعلى.

الخطوة ٤: تنفيذ التصيير على جانب الخادم

تتيح 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: النشر والاختبار!

لقد انتهينا! سيتم الآن ترجمة تطبيق 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!