@intlayer/docs 7.0.0-canary.2 → 7.0.0

package/docs/ar/releases/v7.md

@@ -0,0 +1,485 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: الإصدار الجديد Intlayer v7 - ما الجديد؟
+description: اكتشف ما الجديد في Intlayer v7. تحسينات كبيرة في الأداء، تجربة المطور، وميزات جديدة لتعزيز سير عمل التدويل الخاص بك.
+keywords:
+  - Intlayer
+  - التوطين
+  - التطوير
+  - الأداء
+  - تجربة المطور
+  - الميزات
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# الإصدار الجديد Intlayer v7 - ما الجديد؟
+
+مرحبًا بك في Intlayer v7! يقدم هذا الإصدار الكبير تحسينات ملحوظة في الأداء، أمان الأنواع، وتجربة المطور. فيما يلي أبرز النقاط، مع ملاحظات الترحيل وأمثلة عملية.
+
+## أبرز النقاط
+
+- استراتيجية التخزين المؤقت لبناء أسرع
+- تحسين توليد أنواع TypeScript بأنواع مخصصة لكل لغة
+- تحسين الحزمة: استخدام السلاسل النصية للغات بدلاً من التعداد (enum)
+- أوضاع توجيه جديدة: `prefix-no-default`، `prefix-all`، `no-prefix`، `search-params`
+- تخزين اللغات متوافق مع GDPR باستخدام localStorage كإعداد افتراضي
+- تكوين تخزين مرن: ملفات تعريف الارتباط (cookies)، localStorage، sessionStorage، أو متعددة
+- حجم حزمة محرر المحتوى المرئي أصغر بنسبة 30%
+- خيارات محسنة لتكوين الوسيط (middleware)
+- تحديث سلوك أمر التعبئة (fill) لإدارة محتوى أفضل
+- استقرار محسّن مع تحديثات كاملة لملفات إعلان المحتوى
+- إدارة ذكية لإعادة المحاولة لضمان دقة الترجمة
+- المعالجة المتوازية لتسريع عملية الترجمة
+- تقسيم ذكي للتعامل مع الملفات الكبيرة ضمن حدود سياق الذكاء الاصطناعي
+
+---
+
+## الأداء: التخزين المؤقت لبناء أسرع
+
+بدلاً من إعادة بناء إعلانات المحتوى باستخدام esbuild في كل عملية بناء، تقوم النسخة 7 بتنفيذ استراتيجية تخزين مؤقت تُسرّع عملية البناء.
+
+```bash
+npx intlayer build
+```
+
+نظام التخزين المؤقت الجديد:
+
+- يخزن إعلانات المحتوى المجمعة لتجنب المعالجة المتكررة
+- يكتشف التغييرات ويعيد بناء الملفات المعدلة فقط
+- يقلل بشكل كبير من أوقات البناء للمشاريع الكبيرة
+
+---
+
+## تايب سكريبت: توليد أنواع مخصصة لكل لغة
+
+يتم الآن توليد أنواع TypeScript لكل لغة على حدة، مما يوفر كتابة أقوى ويقضي على أنواع الاتحاد عبر جميع اللغات.
+
+**سلوك النسخة 6:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**سلوك النسخة 7:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+الفوائد:
+
+- إكمال تلقائي أكثر دقة في بيئة التطوير الخاصة بك
+- أمان نوع أفضل بدون تلوث أنواع عبر اللغات المختلفة
+- أداء محسّن من خلال تقليل تعقيد الأنواع
+
+---
+
+## تحسين الحزمة: اللغات كسلاسل نصية
+
+لم يعد نوع `Locales` تعدادًا (enum)، مما يعني أنه أصبح قابلًا لإزالة الشجر بالكامل (tree-shakeable) ولن يثقل حزمة التطبيق الخاصة بك بآلاف سجلات اللغات غير المستخدمة.
+
+**النسخة 6:**
+
+```typescript
+import { Locales } from "intlayer";
+// تعداد يشمل جميع اللغات -> غير قابل لإزالة الشجر
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**النسخة 7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// نوع سلسلة نصية -> قابل لإزالة الشجر بالكامل
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> نظرًا لأن `Locales` لم يعد تعدادًا (enum)، سيتعين عليك تغيير النوع من `Locales` إلى `Locale` للحصول على اللغة كنمط.
+
+راجع [تفاصيل التنفيذ](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) لمزيد من المعلومات.
+
+---
+
+## أوضاع التوجيه الجديدة لمزيد من المرونة
+
+تقدم النسخة 7 تكوينًا موحدًا `routing.mode` يحل محل الخيارات السابقة `prefixDefault` و `noPrefix`، مما يوفر تحكمًا أكثر دقة في هيكل عنوان URL.
+
+### أوضاع التوجيه المتاحة
+
+- **`prefix-no-default`** (الافتراضي): اللغة الافتراضية بدون بادئة، واللغات الأخرى لها بادئة
+  - `/dashboard` (en) أو `/fr/dashboard` (fr)
+- **`prefix-all`**: جميع اللغات لها بادئة
+  - `/en/dashboard` (en) أو `/fr/dashboard` (fr)
+- **`no-prefix`**: لا توجد بادئات للغة في عناوين URL (يتم التعامل مع اللغة عبر التخزين/الرؤوس)
+  - `/dashboard` لجميع اللغات
+- **`search-params`**: تمرير اللغة كمعامل استعلام
+  - `/dashboard?locale=en` أو `/dashboard?locale=fr`
+
+### التكوين الأساسي
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // الافتراضي
+  },
+};
+```
+
+---
+
+## الامتثال للائحة حماية البيانات العامة (GDPR): تخزين localStorage / الكوكيز
+
+تُعطي النسخة 7 أولوية لخصوصية المستخدم باستخدام `localStorage` كآلية التخزين الافتراضية بدلاً من الكوكيز. يساعد هذا التغيير في الامتثال للائحة GDPR من خلال تجنب متطلبات موافقة الكوكيز لتفضيلات اللغة.
+
+### خيارات تكوين التخزين
+
+يتوفر الحقل الجديد `routing.storage` بالإضافة إلى الخيارات السابقة `middleware.cookieName` و `middleware.serverSetCookie`، مما يوفر تكوينات تخزين مرنة:
+
+```typescript
+// تعطيل التخزين
+storage: false
+
+// أنواع التخزين البسيطة
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// الكوكيز مع سمات مخصصة
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage مع مفتاح مخصص
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// أنواع تخزين متعددة للنسخ الاحتياطي
+storage: ['cookie', 'localStorage']
+```
+
+### مثال على تكوين متوافق مع GDPR
+
+للتطبيقات الإنتاجية التي تحتاج إلى موازنة بين الوظائف والامتثال لـ GDPR:
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // التخزين الأساسي (لا يحتاج موافقة)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // تخزين الكوكيز الاختياري (يتطلب موافقة)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### تمكين / تعطيل تخزين الكوكيز
+
+مثال باستخدام React / Next.js:
+
+يمكن تعريفه على مستوى عام:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+يمكن تجاوزه محليًا لكل هوك:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**ملاحظة:** الكوكيز مفعلة بشكل افتراضي.
+**ملاحظة:** تحقق من [متطلبات الكوكيز وفقًا للائحة GDPR](https://gdpr.eu/cookies/) لحالتك الخاصة.
+
+---
+
+## المحرر المرئي: حزمة أصغر بنسبة 30%
+
+تم تحسين حزمة المحرر المرئي لتكون أصغر بنسبة 30% مقارنة بالإصدار السابق، وذلك بفضل:
+
+- تحسينات أداء محرر الكود
+- إزالة التبعيات غير الضرورية على حزم Intlayer الأساسية
+- تحسين تقنيات tree-shaking وتجميع الوحدات
+
+ينتج عن ذلك أوقات تحميل أسرع وأداء أفضل أثناء تشغيل التطبيق الخاص بك.
+
+---
+
+## أمر fill: سلوك محدث لإدارة محتوى أفضل
+
+يقدم الإصدار 7 سلوكًا محسّنًا لأمر `fill`، مما يوفر إدارة محتوى أكثر توقعًا ومرونة:
+
+### سلوك fill الجديد
+
+- **`fill: true`** - يعيد كتابة الملف الحالي بمحتوى مملوء لجميع اللغات
+- **`fill: "path/to/file"`** - يملأ الملف المحدد دون تعديل الملف الحالي
+- **`fill: false`** - يعطل الملء التلقائي تمامًا
+
+### دعم معزز لهياكل المحتوى المعقدة
+
+يدعم أمر fill الآن هياكل إعلان المحتوى المعقدة، بما في ذلك:
+
+- **الكائنات المركبة**: إعلانات المحتوى التي تشير إلى كائنات أخرى
+- **المحتوى المفكك**: المحتوى الذي يستخدم أنماط التفكيك
+- **المراجع المتداخلة**: الكائنات التي تستدعي بعضها البعض في تسلسلات معقدة
+- **هياكل المحتوى الديناميكية**: المحتوى ذو الخصائص الشرطية أو المحسوبة
+
+### الفوائد
+
+- **نية أوضح**: أصبح السلوك أكثر وضوحًا بشأن ما يتم تعديله
+- **فصل أفضل**: يمكن الاحتفاظ بملفات المحتوى منفصلة عن الترجمات المعبأة
+- **تحسين سير العمل**: يتمتع المطورون بمزيد من التحكم في مكان تخزين الترجمات
+- **دعم الهياكل المعقدة**: التعامل مع هياكل محتوى متطورة تحتوي على عدة كائنات مترابطة
+
+### مثال على الاستخدام
+
+```typescript
+// إعادة كتابة الملف الحالي مع جميع اللغات
+const content = {
+  key: "example",
+  fill: true, // يعيد كتابة هذا الملف
+  content: {
+    title: "Hello World",
+  },
+};
+
+// تعبئة ملف منفصل دون تعديل الملف الحالي
+const content = {
+  key: "example",
+  fill: "./translations.json", // ينشئ/يحدث translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// تعطيل التعبئة التلقائية
+const content = {
+  key: "example",
+  fill: false, // لا تعبئة تلقائية
+  content: {
+    title: "Hello World",
+  },
+};
+
+// هيكل محتوى معقد مع كائنات مركبة
+const sharedContent = {
+  buttons: {
+    save: "حفظ",
+    cancel: "إلغاء",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // مراجع لكائنات أخرى
+    sharedContent,
+
+    // محتوى مفكك
+    ...sharedContent,
+
+    // مراجع متداخلة
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "القسم 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## تحسين الاستقرار وإدارة الترجمة
+
+يقدم الإصدار 7 عدة تحسينات لجعل ترجمة المحتوى أكثر موثوقية وكفاءة:
+
+### تحديثات كاملة لملفات إعلان المحتوى
+
+يقوم النظام الآن بتحديث ملفات `.content.{ts,js,cjs,mjs}` بدلاً من التحديثات الجزئية، مما يضمن:
+
+- **سلامة البيانات**: إعادة كتابة الملف بالكامل تمنع التحديثات الجزئية التي قد تؤدي إلى تلف المحتوى
+- **الاتساق**: يتم تحديث جميع اللغات بشكل ذري، مما يحافظ على التزامن
+- **الموثوقية**: يقلل من خطر وجود ملفات محتوى غير مكتملة أو تالفة
+
+### إدارة إعادة المحاولة الذكية
+
+آليات إعادة المحاولة الجديدة تمنع دفع المحتوى بصيغ غير صحيحة، وتتجنب كسر عملية التعبئة بالكامل إذا فشل طلب واحد.
+
+### المعالجة المتوازية لتسريع الأداء
+
+تعمل عمليات الترجمة الآن في قائمة انتظار لتشغيلها بشكل متوازي. هذا يسرع العملية بشكل كبير.
+
+### تقسيم ذكي للملفات الكبيرة
+
+استراتيجيات تقسيم متقدمة تتعامل مع ملفات المحتوى الكبيرة دون تجاوز حدود سياق الذكاء الاصطناعي:
+
+### مثال على سير العمل
+
+```typescript
+// يتم تقسيم ملف المحتوى الكبير تلقائيًا
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // يتم تقسيم المحتوى الكبير تلقائيًا للمعالجة بواسطة الذكاء الاصطناعي
+    introduction: "..." // أكثر من 5000 حرف
+    sections: [
+      // عدة أقسام كبيرة
+    ]
+  }
+};
+```
+
+يقوم النظام تلقائيًا بـ:
+
+1. تحليل حجم المحتوى وبنيته
+2. تقسيم المحتوى بشكل مناسب
+3. معالجة الأجزاء بشكل متوازي
+4. التحقق من الصحة وإعادة المحاولة إذا لزم الأمر
+5. إعادة بناء الملف الكامل
+
+---
+
+## ملاحظات الترحيل من الإصدار v6
+
+### الإعدادات التي تمت إزالتها
+
+- **`middleware.cookieName`**: تم استبداله بـ `routing.storage`
+- **`middleware.serverSetCookie`**: تم استبداله بـ `routing.storage`
+- **`middleware.prefixDefault`**: تم استبداله بـ `routing.mode`
+- **`middleware.noPrefix`**: تم استبداله بـ `routing.mode`
+
+### خريطة الترحيل
+
+#### خريطة التهيئة
+
+| تهيئة v6                   | تهيئة v7                                           |
+| -------------------------- | -------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                        |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                        |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                               |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`   |
+| `serverSetCookie: 'never'` | `storage: false` أو إزالة الكوكي من مصفوفة التخزين |
+
+#### مثال على الترحيل
+
+**قبل (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**بعد (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // أو 'cookie' إذا كنت بحاجة إلى تخزين الكوكيز
+    headerName: "x-intlayer-locale",
+    basePath: "",
+  },
+};
+```
+
+#### مطابقة محتوى القاموس
+
+| محتوى القاموس في v6 | محتوى القاموس في v7 |
+| ------------------- | ------------------- |
+| `autoFill: xxx`     | `fill: xxx`         |
+
+#### مثال على الترحيل
+
+**قبل (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // يعيد كتابة هذا الملف
+  content: {
+    title: "مرحبا بالعالم",
+  },
+};
+```
+
+**بعد (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // يعيد كتابة هذا الملف
+  content: {
+    title: "مرحبا بالعالم",
+  },
+};
+```
+
+---
+
+## ملاحظات الترحيل من الإصدار v5 إلى v6
+
+راجع [ملاحظات الترحيل من v5 إلى v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/releases/v6.md) لمزيد من المعلومات.
+
+---
+
+## روابط مفيدة
+
+- [مرجع التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md)
+- [توثيق الوسيط](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/next-intlayer/index.md)
+- [أنواع TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [إرشادات ملفات تعريف الارتباط وفقًا للائحة GDPR](https://gdpr.eu/cookies/)

package/docs/de/configuration.md

@@ -333,30 +333,6 @@ Einstellungen, die das Verhalten der Middleware steuern, einschließlich wie die
       - Wenn `noPrefix = false`: URL wird `https://example.com/my-app/en` sein
       - Wenn `noPrefix = true`: URL wird `https://example.com` sein
 
-- **detectLocaleOnPrefetchNoPrefix**:
-  - _Typ_: `boolean`
-  - _Standard_: `false`
-  - _Beschreibung_: Steuert, ob die Lokalisierungserkennung während Next.js Prefetch-Anfragen erfolgt.
-  - _Beispiel_: `true`
-  - _Hinweis_: Diese Einstellung beeinflusst, wie Next.js das Prefetching von Lokalisierungen handhabt:
-    - **Beispielszenario:**
-      - Die Browsersprache des Benutzers ist `'fr'`
-      - Aktuelle Seite ist `/fr/about`
-      - Link prefetcht `/about`
-    - **Mit `detectLocaleOnPrefetchNoPrefix: true`:**
-      - Prefetch erkennt die `'fr'`-Lokalisierung aus dem Browser
-      - Prefetch wird zu `/fr/about` umgeleitet
-    - **Mit `detectLocaleOnPrefetchNoPrefix: false` (Standard):**
-      - Prefetch verwendet die Standard-Lokalisierung
-      - Prefetch wird zu `/en/about` umgeleitet (angenommen `'en'` ist Standard)
-    - **Wann `true` verwendet werden sollte:**
-      - Ihre Anwendung verwendet nicht lokalisierte interne Links (z. B. `<a href="/about">`)
-      - Sie möchten ein konsistentes Verhalten bei der Lokalerkennung zwischen regulären und Prefetch-Anfragen
-    - **Wann `false` (Standard) verwenden:**
-      - Ihre Anwendung verwendet lokalisierte Links mit Präfix (z. B. `<a href="/fr/about">`)
-      - Sie möchten die Prefetch-Leistung optimieren
-      - Sie möchten potenzielle Redirect-Schleifen vermeiden
-
 ---
 
 ### Inhaltskonfiguration