استخدم مساعدك المفضل للملخص واستخدم هذه الصفحة والموفر AI الذي تريده
تاريخ الإصدارات
- "تحديث استخدام واجهة برمجة تطبيقات useIntlayer في Solid للوصول المباشر إلى الخصائص"v8.9.0٤/٥/٢٠٢٦
- "الإصدار الأولي"v8.0.0١٠/١/٢٠٢٦
تمت ترجمة محتوى هذه الصفحة باستخدام الذكاء الاصطناعي.
اعرض آخر نسخة المحتوى الأصلي باللغة الإنكليزيةIf you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.
GitHub link to the documentationCopy doc Markdown to clipboard
ترجمة موقعك Next.js 16 (بدون [locale] في مسار الصفحة) باستخدام Intlayer | التدويل (i18n)
اطّلع على قالب التطبيق على GitHub.
جدول المحتويات
لماذا Intlayer على البدائل؟
بالمقارنة مع الحلول الرئيسية مثل next-intl أو i18next، يعد Intlayer حلاً يأتي مزودًا بتحسينات متكاملة مثل:
تغطية Next.js الكاملة
تم تحسين Intlayer للعمل مع مكونات الخادم من أجل العرض الفعال وهو متوافق تمامًا مع Turbopack. إنه لا يمنع العرض الثابت ويوفر برامج وسيطة بالإضافة إلى جميع الميزات اللازمة لتوسيع نطاق التدويل (i18n).
يتوافق Intlayer مع Next.js 12 و13 و14 و15 و16. إذا كنت تستخدم جهاز توجيه الصفحات Next.js، فيمكنك الرجوع إلى هذا الدليل. يعد التوجيه المحلي مفيدًا لتحسين محركات البحث وحجم البندل والأداء. إذا لم تكن بحاجة إليه، يمكنك الرجوع إلى هذا الدليل. بالنسبة إلى Next.js 12 و13 و14 و15 مع جهاز توجيه التطبيقات، راجع هذا الدليل.
حجم البندل
بدلاً من تحميل ملفات JSON ضخمة إلى صفحاتك، قم بتحميل المحتوى الضروري فقط. يساعد Intlayer في تقليل أحجام البندل وصفحاتك بنسبة تصل إلى 50%.
الصيانة
يؤدي تحديد نطاق محتوى تطبيقك إلى تسهيل الصيانة للتطبيقات واسعة النطاق. يمكنك تكرار أو حذف مجلد ميزات واحد دون العبء العقلي لمراجعة قاعدة بيانات المحتوى بالكامل. بالإضافة إلى ذلك، تتم كتابة Intlayer بالكامل لضمان دقة المحتوى الخاص بك.
وكيل الذكاء الاصطناعي
يؤدي تحديد موقع المحتوى المشترك إلى تقليل السياق المطلوب بواسطة نماذج اللغات الكبيرة (LLMs). يأتي Intlayer أيضًا مزودًا بمجموعة من الأدوات، مثل CLI لاختبار الترجمات المفقودة،LSP، MCP ومهارات الوكيل، لجعل تجربة المطور (DX) أكثر سلاسة للذكاء الاصطناعي وكلاء.
الأتمتة
استخدم الأتمتة للترجمة في مسار CI/CD الخاص بك باستخدام LLM من اختيارك على حساب مزود الذكاء الاصطناعي الخاص بك. يقدم Intlayer أيضًا مترجمًا لأتمتة استخراج المحتوى، بالإضافة إلى منصة ويب للمساعدة في الترجمة في الخلفية.
أداء
يمكن أن يؤدي ربط ملفات JSON الضخمة بالمكونات إلى حدوث مشكلات في الأداء والتفاعل. يعمل Intlayer على تحسين تحميل المحتوى الخاص بك في وقت الإنشاء.
التحجيم مع عدم وجود مطور
أكثر من مجرد حل i18n، يوفر Intlayer [محررًا مرئيًا] مستضافًا ذاتيًا](/ar/doc/concept/editor) وكامل CMS لمساعدتك في إدارة المحتوى متعدد اللغات في الوقت الفعلي، مما يجعل التعاون مع المترجمين ومؤلفي النصوص وأعضاء الفريق الآخرين سلسًا. يمكن تخزين المحتوى محليًا و/أو عن بعد.
دليل خطوة بخطوة لإعداد Intlayer في تطبيق Next.js
تثبيت التبعيات
قم بتثبيت الحزم اللازمة باستخدام npm:
bashنسخ الكودنسخ الكود إلى الحافظة
npm install intlayer next-intlayernpx intlayer initintlayer
الحزمة الأساسية التي توفّر أدوات التعريب لإدارة التهيئة، والترجمة، وإعلان المحتوى، والـتحويل البرمجي (transpilation)، وأوامر CLI.
next-intlayer
الحزمة التي تدمج Intlayer مع Next.js. توفر مزودات السياق (context providers) والـ hooks لدعم التدويل في Next.js. بالإضافة إلى ذلك، تتضمن مكون Next.js الإضافي (plugin) لربط Intlayer مع Webpack أو Turbopack، وكذلك بروكسي لاكتشاف لغة المستخدم المفضلة، وإدارة الكوكيز، ومعالجة إعادة توجيه URL.
تكوين مشروعك
فيما يلي البنية النهائية التي سننشئها:
bashنسخ الكودنسخ الكود إلى الحافظة
.├── src│ ├── app│ │ ├── layout.tsx│ │ ├── page.content.ts│ │ └── page.tsx│ ├── components│ │ ├── clientComponentExample│ │ │ ├── client-component-example.content.ts│ │ │ └── ClientComponentExample.tsx│ │ ├── localeSwitcher│ │ │ ├── localeSwitcher.content.ts│ │ │ └── LocaleSwitcher.tsx│ │ └── serverComponentExample│ │ ├── server-component-example.content.ts│ │ └── ServerComponentExample.tsx│ └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.jsonإذا كنت لا تريد توجيه المسارات حسب اللغة، يمكن استخدام intlayer كمزود (provider) أو hook بسيط. راجع هذا الدليل لمزيد من التفاصيل.
أنشئ ملف تكوين لتحديد لغات تطبيقك:
intlayer.config.tsنسخ الكودنسخ الكود إلى الحافظة
import { Locales, type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // بقية اللغات الخاصة بك ], defaultLocale: Locales.ENGLISH, }, routing: { mode: "search-params", // أو `no-prefix` - مفيد لاكتشاف الوسيط (middleware) }, }; export default config;من خلال ملف التكوين هذا، يمكنك إعداد عناوين URL محلية، وإعادة توجيه البروكسي، وأسماء ملفات تعريف الارتباط، وموقع وامتداد تعريفات المحتوى الخاصة بك، وتعطيل سجلات Intlayer في وحدة التحكم، والمزيد. لقائمة كاملة بالمعلمات المتاحة، راجع توثيق التكوين.
دمج Intlayer في تكوين Next.js الخاص بك
قم بتكوين إعداد Next.js الخاص بك لاستخدام Intlayer:
next.config.tsنسخ الكودنسخ الكود إلى الحافظة
import type { NextConfig } from "next"; import { withIntlayer } from "next-intlayer/server"; const nextConfig: NextConfig = { /* خيارات التكوين هنا */ }; export default withIntlayer(nextConfig);يُستخدم مكوّن Next.js الإضافي
withIntlayer()لدمج Intlayer مع Next.js. يضمن بناء ملفات إعلان المحتوى ويقوم بمراقبتها في وضع التطوير. يعرّف متغيرات بيئة Intlayer داخل بيئات Webpack أو Turbopack. بالإضافة إلى ذلك، يوفر aliases لتحسين الأداء ويضمن التوافق مع مكونات الخادم.دالة
withIntlayer()هي دالة تُعيد Promise. تتيح تحضير قواميس intlayer قبل بدء عملية البناء. إذا أردت استخدامها مع إضافات (plugins) أخرى، يمكنك انتظارها باستخدام await. مثال:tsنسخ الكودنسخ الكود إلى الحافظة
const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;إذا رغبت في استخدامه بشكل متزامن، يمكنك استخدام الدالة
withIntlayerSync(). مثال:tsنسخ الكودنسخ الكود إلى الحافظة
const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;يكتشف Intlayer تلقائياً ما إذا كان مشروعك يستخدم webpack أو Turbopack بناءً على وسائط سطر الأوامر
--webpack،--turbo، أو--turbopack، وكذلك اعتماداً على إصدار Next.js الحالي لديك.بما أن
next>=16، إذا كنت تستخدم Rspack، يجب عليك إجبار Intlayer صراحةً على استخدام إعداد webpack عن طريق تعطيل Turbopack:tsنسخ الكودنسخ الكود إلى الحافظة
withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));تعريف مسارات اللغة الديناميكية
أزل كل شيء من
RootLayoutواستبدله بالشيفرة التالية:src/app/layout.tsxنسخ الكودنسخ الكود إلى الحافظة
import type { Metadata } from "next"; import type { ReactNode } from "react"; import "./globals.css"; import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer"; import { getHTMLTextDir, getIntlayer } from "intlayer"; import { getLocale } from "next-intlayer/server"; export { generateStaticParams } from "next-intlayer"; export const generateMetadata = async (): Promise<Metadata> => { const locale = await getLocale(); const { title, description, keywords } = getIntlayer("metadata", locale); return { title, description, keywords, }; }; const RootLayout = async ({ children, }: Readonly<{ children: ReactNode; }>) => { const locale = await getLocale(); return ( <html lang={locale} dir={getHTMLTextDir(locale)}> <IntlayerClientProvider defaultLocale={locale}> <body>{children}</body> </IntlayerClientProvider> </html> ); }; export default RootLayout;أعلن محتواك
قم بإنشاء وإدارة تصريحات المحتوى الخاصة بك لتخزين الترجمات:
src/app/metadata.content.tsنسخ الكودنسخ الكود إلى الحافظة
import { t, type Dictionary } from "intlayer"; import { Metadata } from "next"; const metadataContent = { key: "metadata", content: { title: t({ ar: "عنوان المشروع الخاص بي", en: "My Project Title", fr: "Le Titre de mon Projet", es: "El Título de mi Proyecto", }), description: t({ ar: "اكتشف منصتنا المبتكرة المصممة لتبسيط سير عملك وزيادة إنتاجيتك.", en: "Discover our innovative platform designed to streamline your workflow and boost productivity.", fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.", es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.", }), keywords: t({ ar: ["الابتكار", "الإنتاجية", "سير العمل", "SaaS"], en: ["innovation", "productivity", "workflow", "SaaS"], ar: ["الابتكار", "الإنتاجية", "سير العمل", "SaaS"], fr: ["innovation", "productivité", "flux de travail", "SaaS"], es: ["innovación", "productividad", "flujo de trabajo", "SaaS"], }), }, } as Dictionary<Metadata>; export default metadataContent;src/app/page.content.tsنسخ الكودنسخ الكود إلى الحافظة
import { t, type Dictionary } from "intlayer"; const pageContent = { key: "page", content: { getStarted: { main: t({ ar: "ابدأ بالتعديل", en: "Get started by editing", fr: "Commencez par éditer", es: "Comience por editar", }), pageLink: "src/app/page.tsx", }, }, } satisfies Dictionary; export default pageContent;يمكن تعريف إعلانات المحتوى (content declarations) في أي مكان داخل تطبيقك طالما أنها موجودة داخل دليل
contentDir(افتراضيًا./src). ويجب أن يتطابق امتداد ملف إعلان المحتوى (افتراضيًا.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).لمزيد من التفاصيل، راجع توثيق إعلان المحتوى.
استخدام المحتوى في الشيفرة الخاصة بك
الوصول إلى قواميس المحتوى في جميع أنحاء تطبيقك:
src/app/page.tsxنسخ الكودنسخ الكود إلى الحافظة
import type { FC } from "react"; import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample"; import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample"; import { IntlayerServerProvider, useIntlayer, getLocale, } from "next-intlayer/server"; import { NextPage } from "next"; import { headers, cookies } from "next/headers"; const PageContent: FC = () => { const content = useIntlayer("page"); return ( <> <p>{content.getStarted.main}</p> <code>{content.getStarted.pageLink}</code> </> ); }; const Page: NextPage = async () => { const locale = await getLocale(); return ( <IntlayerServerProvider locale={locale}> <PageContent /> <ServerComponentExample /> <ClientComponentExample /> </IntlayerServerProvider> ); }; export default Page;IntlayerClientProviderيُستخدم لتوفير الـ locale للمكونات على جانب العميل. يمكن وضعه في أي مكوّن أصل (parent component)، بما في ذلك الـ layout. ومع ذلك، يُنصح بوضعه في الـ layout لأن Next.js يشارك كود الـ layout عبر الصفحات، مما يجعله أكثر كفاءة. باستخدامIntlayerClientProviderداخل الـ layout، تتجنّب إعادة تهيئته لكل صفحة، مما يحسّن الأداء ويحافظ على سياق التعريب المتسق في تطبيقك.IntlayerServerProviderتُستخدم لتزويد العناصر الفرعية التي تعمل على الخادم بالـ locale. لا يمكن تعيينها في الـ layout.لا يمكن أن يتشارك الـ layout والصفحة نفس سياق الخادم لأن نظام سياق الخادم يعتمد على مخزن بيانات لكل طلب (عبر آلية React's cache)، مما يجعل كل "context" يُعاد إنشاؤه لأجزاء مختلفة من التطبيق. وضع الـ provider في layout مشترك سيكسر هذا العزل، وسيمنع الانتشار الصحيح لقيم سياق الخادم إلى مكوناتك على الخادم.
src/components/clientComponentExample/ClientComponentExample.tsxنسخ الكودنسخ الكود إلى الحافظة
"use client"; import type { FC } from "react"; import { useIntlayer } from "next-intlayer"; export const ClientComponentExample: FC = () => { const content = useIntlayer("client-component-example"); // إنشاء تعريف المحتوى المرتبط return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> ); };src/components/serverComponentExample/ServerComponentExample.tsxنسخ الكودنسخ الكود إلى الحافظة
import type { FC } from "react"; import { useIntlayer } from "next-intlayer/server"; export const ServerComponentExample: FC = () => { const content = useIntlayer("server-component-example"); // إنشاء تعريف المحتوى المرتبط return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> ); };يُستخدم
intlayerProxyلاكتشاف اللغة المفضلة للمستخدم وإعادة توجيهه إلى عنوان URL المناسب كما هو موضح في التكوين. بالإضافة إلى ذلك، يتيح حفظ اللغة المفضلة للمستخدم في ملف تعريف الارتباط (cookie).إذا احتجت إلى ربط عدة proxies معًا (على سبيل المثال،
intlayerProxyمع المصادقة أو proxies مخصصة)، فإن Intlayer يوفر الآن مساعدًا يسمىmultipleProxies.tsنسخ الكودنسخ الكود إلى الحافظة
import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);تغيير لغة المحتوى الخاص بك
اختياريلتغيير لغة المحتوى في Next.js، الطريقة الموصى بها هي استخدام مكوّن Link لإعادة توجيه المستخدمين إلى الصفحة المحلية المناسبة. يتيح مكوّن Link إمكانية التحميل المسبق للصفحة (prefetching)، مما يساعد على تجنّب إعادة تحميل الصفحة بالكامل.
src/components/localeSwitcher/LocaleSwitcher.tsxنسخ الكودنسخ الكود إلى الحافظة
"use client"; import type { FC } from "react"; import { Locales, getHTMLTextDir, getLocaleName } from "intlayer"; import { useLocale } from "next-intlayer"; export const LocaleSwitcher: FC = () => { const { locale, availableLocales, setLocale } = useLocale(); return ( <div> <button popoverTarget="localePopover">{getLocaleName(locale)}</button> <div id="localePopover" popover="auto"> {availableLocales.map((localeItem) => ( <button key={localeItem} aria-current={locale === localeItem ? "page" : undefined} onClick={() => setLocale(localeItem)} > <span> {/* اللغة - مثال: FR */} {localeItem} </span> <span> {/* اللغة بلغة نفسها - مثال: Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* اللغة بالترجمة الحالية - مثال: Francés مع تعيين locale الحالي إلى Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* اللغة بالإنجليزية - على سبيل المثال: French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </button> ))} </div> </div> ); };طريقة بديلة هي استخدام الدالة
setLocaleالمقدمة من الـuseLocaleهوك. هذه الدالة لن تسمح بالتحميل المسبق للصفحة. راجع توثيقuseLocaleهوك لمزيد من التفاصيل.مراجع التوثيق:
الحصول على اللغة الحالية في Server Actions
اختياريإذا احتجت إلى الـ locale النشط داخل Server Action (مثلًا، لتوطين رسائل البريد الإلكتروني أو لتنفيذ منطق يتعامل مع اللغة)، استدعِ
getLocaleمنnext-intlayer/server:src/app/actions/getLocale.tsنسخ الكودنسخ الكود إلى الحافظة
"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => { const locale = await getLocale(); // قم بعمل شيء باستخدام المتغير locale};تتبع الدالة
getLocaleاستراتيجية متدرجة لتحديد لغة المستخدم:- أولاً، تتحقق من request headers عن قيمة locale قد تكون قد تم تعيينها بواسطة proxy
- إذا لم يتم العثور على locale في الرؤوس، فإنها تبحث عن locale مخزنة في cookies
- إذا لم يتم العثور على cookie، تحاول اكتشاف اللغة المفضلة للمستخدم من إعدادات الـ browser
- كملاذ أخير، تعود إلى الـ default locale المكوّن للتطبيق
هذا يضمن اختيار الـlocale الأنسب بناءً على السياق المتاح.
تحسين حجم البندل
اختياريعند استخدام
next-intlayer، يتم تضمين القواميس في كل bundle لكل صفحة بشكل افتراضي. لتقليل حجم الـbundle، يوفر Intlayer ملحق SWC اختياري يستبدل استدعاءاتuseIntlayerبذكاء باستخدام الماكروز. هذا يضمن تضمين القواميس فقط في الحزم الخاصة بالصفحات التي تستخدمها فعليًا.لتمكين هذا التحسين، ثبّت الحزمة
@intlayer/swc. بمجرد التثبيت، سيكتشفnext-intlayerالملحق ويستخدمه تلقائيًا:bashنسخ الكودنسخ الكود إلى الحافظة
npm install @intlayer/swc --save-devملاحظة: هذا التحسين متاح فقط لـ Next.js 13 والإصدارات الأحدث.
ملاحظة: هذه الحزمة غير مثبتة افتراضيًا لأن إضافات SWC لا تزال تجريبية في Next.js. قد يتغير ذلك في المستقبل.
ملاحظة: إذا قمت بتعيين الخيار إلى
importMode: 'dynamic'أوimportMode: 'fetch'، فسيعتمد ذلك على Suspense، لذا سيتوجب عليك تغليف استدعاءاتuseIntlayerضمن حدّSuspense. هذا يعني أنك لن تتمكن من استخدامuseIntlayerمباشرةً على المستوى العلوي لمكوّن الصفحة / التخطيط الخاص بك.
مراقبة تغيّرات القواميس على Turbopack
عند استخدام Turbopack كسيرفر التطوير مع الأمر next dev، فلن يتم اكتشاف تغييرات القواميس تلقائيًا افتراضيًا.
يحدث هذا القيد لأن Turbopack لا يستطيع تشغيل ملحقات webpack بالتوازي لمراقبة التغييرات في ملفات المحتوى الخاصة بك. كحل بديل، ستحتاج إلى استخدام الأمر intlayer watch لتشغيل كلٍ من سيرفر التطوير ومراقب بناء Intlayer في آنٍ واحد.
نسخ الكود إلى الحافظة
{ // ... Your existing package.json configurations "scripts": { // ... Your existing scripts configurations "dev": "intlayer watch --with 'next dev'", },}إذا كنت تستخدم next-intlayer@<=6.x.x، تحتاج إلى الاحتفاظ بالعلم --turbopack لجعل تطبيق Next.js 16 يعمل بشكل صحيح مع Turbopack. نوصي باستخدام next-intlayer@>=7.x.x لتجنب هذا القيد.
تكوين TypeScript
يستخدم Intlayer module augmentation للاستفادة من TypeScript وتقوية الـ codebase الخاصة بك.


تأكد من أن إعدادات TypeScript تتضمن الأنواع المولدة تلقائيًا.
نسخ الكود إلى الحافظة
{ // ... تكوينات TypeScript الحالية الخاصة بك "include": [ // ... تكوينات TypeScript الحالية الخاصة بك ".intlayer/**/*.ts", // تضمين الأنواع المولدة تلقائيًا ],}تهيئة Git
يوصى بتجاهل الملفات المولدة بواسطة Intlayer. يسمح لك هذا بتجنّب إضافتها إلى مستودع Git الخاص بك.
للقيام بذلك، يمكنك إضافة التعليمات التالية إلى ملف .gitignore الخاص بك:
نسخ الكود إلى الحافظة
# تجاهل الملفات المولدة بواسطة Intlayer.intlayerامتداد VS Code
لتحسين تجربة التطوير مع Intlayer، يمكنك تثبيت الامتداد الرسمي Intlayer VS Code Extension.
يوفر هذا الامتداد:
- Autocompletion لمفاتيح الترجمة.
- Real-time error detection للترجمات المفقودة.
- معاينات مضمنة للمحتوى المترجم.
- إجراءات سريعة لإنشاء التراجمات وتحديثها بسهولة.
للمزيد من التفاصيل حول كيفية استخدام الامتداد، راجع توثيق امتداد Intlayer لـ VS Code: Intlayer VS Code Extension documentation.
التوسع
للتوسع، يمكنك تنفيذ المحرر المرئي أو إخراج محتواك باستخدام نظام إدارة المحتوى (CMS).