@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/ar/migration_from_vue-i18n_to_intlayer.md

@@ -0,0 +1,359 @@
+---
+createdAt: 2026-06-05
+updatedAt: 2026-06-05
+title: "الترحيل من vue-i18n إلى Intlayer | التدويل (i18n)"
+description: "تعرّف على كيفية ترحيل تطبيق Vue أو Nuxt الخاص بك من vue-i18n إلى Intlayer — خطوة بخطوة، دون كسر الكود الموجود. استخدم محول التوافق @intlayer/vue-i18n للانتقال بدون انقطاع."
+keywords:
+  - vue-i18n
+  - intlayer
+  - ترحيل
+  - تدويل
+  - i18n
+  - Nuxt
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - migration
+  - vue-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-05
+    changes: "بدء السجل"
+author: aymericzip
+---
+
+# الترحيل من vue-i18n إلى Intlayer
+
+## لماذا الترحيل من vue-i18n إلى Intlayer؟
+
+<AccordionGroup>
+
+<Accordion header="حجم الحزمة">
+
+بدلاً من تحميل ملفات JSON ضخمة في صفحاتك، قم بتحميل فقط المحتوى الضروري. يساعد Intlayer على **تقليل حجم الحزمة والصفحات بما يصل إلى 50%**.
+
+</Accordion>
+
+<Accordion header="سهولة الصيانة">
+
+يسهل تحديد نطاق محتوى التطبيق **الصيانة** للتطبيقات واسعة النطاق. يمكنك نسخ أو حذف مجلد ميزة واحد دون الحاجة لمراجعة كود المحتوى بالكامل. بالإضافة إلى ذلك، Intlayer **مكتوب بشكل كامل** لضمان دقة المحتوى الخاص بك.
+
+Intlayer أيضاً هو الحل ذو **التطوير الأكثر نشاطاً** في نظام i18n البيئي — تُصلح المشاكل بسرعة، وتُضاف محولات إطار عمل جديدة بانتظام، ويتم تحسين API الأساسي بناءً على ملاحظات الإنتاج الحقيقية.
+
+</Accordion>
+
+<Accordion header="وكيل ذكي">
+
+يقلل دمج المحتوى **السياق المطلوب** من نماذج اللغة الكبيرة (LLMs). يأتي Intlayer أيضاً مع مجموعة من الأدوات، مثل **CLI** لاختبار الترجمات المفقودة، **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/lsp.md)**، **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/mcp_server.md)**، و**[مهارات الوكيل](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/agent_skills.md)**، لجعل تجربة المطور (DX) أكثر سلاسة حتى للوكلاء الذكيين.
+
+</Accordion>
+
+<Accordion header="الأتمتة">
+
+استخدم الأتمتة للترجمة في خط أنابيب CI/CD الخاص بك باستخدام نموذج LLM من اختيارك بتكلفة موفر الذكاء الاصطناعي الخاص بك. يوفر Intlayer أيضاً **compiler** لأتمتة استخراج المحتوى، بالإضافة إلى [منصة ويب](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_CMS.md) لمساعدتك على **الترجمة في الخلفية**.
+
+</Accordion>
+
+<Accordion header="الأداء">
+
+قد يؤدي ربط ملفات JSON الضخمة بالمكونات إلى مشاكل الأداء والاستجابة. يحسّن Intlayer تحميل المحتوى الخاص بك في وقت البناء.
+
+</Accordion>
+
+<Accordion header="التوسع مع غير المطورين">
+
+أكثر من مجرد حل i18n، يوفر Intlayer **[محرر مرئي](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_visual_editor.md)** ذاتي الاستضافة و**[CMS كامل](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_CMS.md)** لمساعدتك على إدارة محتواك متعدد اللغات في **الوقت الفعلي**، مما يجعل التعاون مع المترجمين والكتاب والأعضاء الآخرين في الفريق بسيطاً. يمكن تخزين المحتوى محلياً و/أو بعداً.
+
+</Accordion>
+
+</AccordionGroup>
+
+---
+
+## استراتيجيات الترحيل
+
+هناك استراتيجيتان متكاملتان للترحيل من `vue-i18n` إلى Intlayer:
+
+1. **محول التوافق (موصى به للتطبيقات الموجودة)** — قم بتثبيت `@intlayer/vue-i18n` (لمكونات Vue). تكشف هذه الحزمة عن **نفس API تماماً** من `vue-i18n` ولكن تفوض كل عمل الترجمة إلى Intlayer تحت الغطاء. تحافظ على استدعاءات `$t` و `useI18n()` و `<i18n-t>` الموجودة — التغيير الوحيد هو مسار الاستيراد والتهيئة.
+
+2. **الترحيل الكامل** — استبدل تدريجياً APIs من vue-i18n بـ hooks Intlayer الأصلية (`useIntlayer`) ودمج المحتوى في ملفات `.content.ts` بجانب المكونات الخاصة بك.
+
+يغطي هذا الدليل **الاستراتيجية 1** أولاً (محول التوافق drop-in)، ثم يرشدك عبر الترحيل الكامل الاختياري.
+
+---
+
+## جدول المحتويات
+
+<TOC/>
+
+---
+
+## الترحيل السريع
+
+الخطوات التالية هي الحد الأدنى المطلوب لتشغيل تطبيق `vue-i18n` الموجود على Intlayer بدون تغيير الكود في المكونات.
+
+<Steps>
+
+<Step number={1} title="تثبيت التبعيات">
+
+قم بتثبيت حزم Intlayer الأساسية ومحول التوافق:
+
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> العلم `--interactive` اختياري. استخدم `intlayer-cli init` إذا كنت وكيل ذكي.
+
+> سيكتشف هذا الأمر بيئتك وسيثبت الحزم المطلوبة. على سبيل المثال:
+
+```bash packageManager="npm"
+npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+```
+
+```bash packageManager="yarn"
+yarn add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+```
+
+```bash packageManager="bun"
+bun add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+```
+
+> يمكنك الاحتفاظ بـ `vue-i18n` مثبتة — يستخدم محول التوافق كـ `devDependency` / `peerDependency` لأنواع TypeScript.
+
+</Step>
+
+<Step number={2} title="تكوين Intlayer">
+
+ينشئ أمر `intlayer init` ملف `intlayer.config.ts` بدء. حدثّه ليطابق البيئات المحلية الموجودة لديك وأشر إلى مكوّن `syncJSON` في ملفات الرسائل الخاصة بك:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // أضف جميع البيئات المحلية الموجودة لديك هنا
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      // يطابق صيغة ملاصقات vue-i18n: {name}
+      format: "icu",
+      source: ({ locale }) => `./src/locales/${locale}.json`,
+      location: "src/locales",
+    }),
+  ],
+};
+
+export default config;
+```
+
+> **`source`** يعيّن بيئة محلية إلى مسار ملف JSON الخاص بها. **`location`** يخبر مراقب Intlayer أي مجلد للبحث عن التغييرات. يضمن الخيار `format: 'icu'` أن الملاصقات يتم تحليلها بشكل صحيح لـ `vue-i18n`.
+
+</Step>
+
+<Step number={3} title="إضافة مكوّن Intlayer إلى Bundler الخاص بك">
+
+غلّف تكوين bundler الموجود مع مكوّن التوافق. يُنشئ هذا مكوّن Intlayer الأساسي، ويوصل مراقبة المحتوى، و— بشكل حاسم — **يحقن اسم مستعار module** حتى استدعاءات `import … from 'vue-i18n'` الموجودة لديك تُعاد توجيهها بشفافية إلى `@intlayer/vue-i18n` في وقت البناء. لا يلزم تغيير ملفات المصدر.
+
+**لـ Vite:**
+
+```typescript fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
+```
+
+> `vueI18nVitePlugin()` يغلف مكوّن `intlayer()` من `vite-intlayer` ويضيف اسم مستعار `vue-i18n`. يجمّع المكوّن العادي `intlayer()` من `vite-intlayer` القواامس ولكن **لا** يضيف الاسم المستعار — يمكنك حينها إعادة تسمية الاستيرادات إلى `@intlayer/vue-i18n` يدويياً (انظر الخطوة 4).
+
+**لـ Nuxt:**
+
+إذا كنت تستخدم `@nuxtjs/i18n` (تكامل Nuxt)، قم بتثبيت `nuxt-intlayer` وأضفها إلى `nuxt.config.ts` الخاص بك:
+
+```bash packageManager="npm"
+npm install nuxt-intlayer
+```
+
+```typescript fileName="nuxt.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+export default defineNuxtConfig({
+  modules: ["nuxt-intlayer"],
+  // يمكنك إزالة @nuxtjs/i18n من مكوّنات الخاصة بك بأمان
+});
+```
+
+> **لا تحتاج بعد الآن إلى `createI18n()` أو bootstrap provider يدويياً.** يجمّع Intlayer جميع القواامس في **وقت البناء**، حيث لا توجد خطوة تحميل runtime. يتولى provider المُحتفَظ به التهيئة لك.
+
+</Step>
+
+</Steps>
+
+هذا كل شيء للترحيل السريع. يعمل التطبيق الخاص بك الآن على Intlayer مع الاحتفاظ بكل استيراد ومكون API من `vue-i18n`.
+
+> **مفاتيح ترجمة مكتوبة — تلقائي.** بمجرد أن يجمّع Intlayer القواامس الخاصة بك، يُكتب `useI18n` مقابل المحتوى الفعلي الخاص بك عندما تمرر خيار `namespace`. يتم إكمال المفاتيح تلقائياً في IDE الخاص بك وتسبب المسارات غير الصحيحة أخطاء TypeScript في وقت البناء — لا يلزم أي إعداد إضافي.
+>
+> ```ts
+> // 'about' هو مفتاح قاموس مسجل
+> const { t } = useI18n({ namespace: "about" });
+> t("counter.label"); // ✓ مكمل تلقائياً
+> t("does.not.exist"); // ✗ خطأ TypeScript
+> ```
+
+---
+
+## الترحيل الكامل
+
+الخطوات أدناه اختيارية ويمكن إنجازها بشكل تدريجي. تفتح مجموعة ميزات Intlayer الكاملة: محرر مرئي، CMS، ملفات محتوى مكتوبة، ترجمة مدفوعة بالذكاء الاصطناعي، والمزيد.
+
+<Steps>
+
+<Step number={4} title="إعادة تسمية الاستيراد الصريحة (اختياري)" isOptional={true}>
+
+تتعامل مكوّنات Intlayer بالفعل مع الأسماء المستعارة على مستوى bundler. إذا كنت تفضل جعل التبعية صريحة في ملفات المصدر الخاصة بك، يمكنك إعادة تسمية الاستيرادات يدويياً:
+
+| قبل                                     | بعد                                               |
+| --------------------------------------- | ------------------------------------------------- |
+| `import { useI18n } from 'vue-i18n'`    | `import { useI18n } from '@intlayer/vue-i18n'`    |
+| `import { createI18n } from 'vue-i18n'` | `import { createI18n } from '@intlayer/vue-i18n'` |
+
+هذه **بدائل drop-in** — لا تغييرات في توقيعات الدالة أو الحجج أو أنواع الإرجاع مطلوبة.
+
+</Step>
+
+<Step number={5} title="تفعيل أتمتة الترجمة المدفوعة بالذكاء الاصطناعي" isOptional={true}>
+
+بمجرد توصيل Intlayer، استخدم CLI الخاص به لملء الترجمات المفقودة تلقائياً:
+
+```bash packageManager="npm"
+# اختبر الترجمات المفقودة (أضف إلى CI)
+npx intlayer test
+
+# ملء الترجمات المفقودة بـ AI
+npx intlayer fill
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer test
+pnpm intlayer fill
+```
+
+```bash packageManager="yarn"
+yarn intlayer test
+yarn intlayer fill
+```
+
+```bash packageManager="bun"
+bun x intlayer test
+bun x intlayer fill
+```
+
+أضف تكوين AI إلى `intlayer.config.ts`:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "icu",
+      source: ({ locale }) => `./src/locales/${locale}.json`,
+      location: "src/locales",
+    }),
+  ],
+  ai: {
+    apiKey: process.env.OPENAI_API_KEY,
+    // provider: "openai",     // افتراضي
+    // model: "gpt-4o-mini",   // افتراضي
+  },
+};
+
+export default config;
+```
+
+> انظر [وثائق Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/index.md) لجميع الخيارات المتاحة.
+
+</Step>
+
+</Steps>
+
+---
+
+## ما يمكنك حذفه بعد الترحيل
+
+بمجرد وضع محولات التوافق، يمكن إزالة نموذج `vue-i18n` التالي:
+
+| الملف / النمط                      | لماذا لم تعد هناك حاجة                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| استدعاءات `createI18n()`           | تهيّئ provider من Intlayer كل شيء تلقائياً؛ لا توجد خطوة تحميل runtime.                                             |
+| تسجيل Vue plugin (`app.use(i18n)`) | يتولى مكوّن Intlayer الحقن والـ bootstrapping تحت الغطاء.                                                           |
+| حزم اللغات JSON (`locales/*.json`) | تُحتاج حزم JSON فقط إذا كنت تستخدم مكوّن `syncJSON` بعد. بمجرد الترحيل إلى ملفات `.content.ts` يمكنك حذف مجلد JSON. |
+
+عندما تكون جاهزاً للمضي أبعد، يكتشف Intlayer **تلقائياً جميع ملفات `.content.ts` و `.content.json` في أي مكان في قاعدة الكود الخاصة بك** (افتراضياً، في أي مكان داخل `./src`). يمكنك وضع ملف `my-component.content.ts` بجانب `MyComponent.vue` مباشرة وسيلتقطه Intlayer في وقت البناء بدون تكوين إضافي — لا استيرادات، لا تسجيل، لا حاجة لملف فهرس مركزي. هذا يجعل دمج الترجمات مع الصفحات والمكونات بدون احتكاك تماماً.
+
+---
+
+## تكوين TypeScript
+
+يستخدم Intlayer module augmentation لتوفير intellisense TypeScript الكامل لمفاتيح الترجمة الخاصة بك. تأكد من أن `tsconfig.json` الخاص بك يتضمن الأنواع المُنتجة تلقائياً:
+
+```json5 fileName="tsconfig.json"
+{
+  // ... تكوينات TypeScript الموجودة لديك
+  "include": [
+    // ... تكوينات TypeScript الموجودة لديك
+    ".intlayer/**/*.ts", // تضمين الأنواع المُنتجة تلقائياً
+  ],
+}
+```
+
+---
+
+## تكوين Git
+
+أضف مجلد Intlayer المُنتج إلى `.gitignore` الخاص بك:
+
+```plaintext fileName=".gitignore"
+# تجاهل الملفات المُنتجة بواسطة Intlayer
+.intlayer
+```
+
+---
+
+## اذهب أبعد
+
+- **محرر مرئي** — إدارة الترجمات بصرياً في متصفحك: [محرر Intlayer المرئي](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_visual_editor.md)
+- **CMS** — خارج الخدمة وإدارة المحتوى بعداً: [CMS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_CMS.md)
+- **VS Code Extension** — الحصول على الإكمال التلقائي واكتشاف أخطاء الترجمة في الوقت الفعلي: [ملحق Intlayer VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/vs_code_extension.md)
+- **مرجع CLI** — قائمة كاملة بأوامر CLI: [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/index.md)
+- **Intlayer مع Vue** — دليل الإعداد الكامل لـ Vue: [intlayer_with_vite+vue.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+vue.md)
+- **Intlayer مع Nuxt** — دليل الإعداد الكامل لـ Nuxt: [intlayer_with_nuxt.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_nuxt.md)

package/docs/ar/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: توثيق حزمة @intlayer/babel
+description: إضافات Babel لـ Intlayer تُعالج استخراج المحتوى، وتحسين الاستيراد، وتنقية الحقول غير المستخدمة، وتصغير أسماء الحقول أثناء البناء.
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - internationalization
+  - i18n
+  - compiler
+  - optimize
+  - purge
+  - minify
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "توحيد توثيق جميع الصادرات"
+author: aymericzip
+---
+
+# حزمة @intlayer/babel
+
+توفر حزمة `@intlayer/babel` مجموعة من إضافات Babel المتخصصة لـ Intlayer. تُغطي دورة البناء الكاملة: استخراج تصريحات المحتوى، وإعادة كتابة استدعاءات `useIntlayer` / `getIntlayer` إلى استيرادات قواميس مُحسَّنة، وتنقية الحقول غير المستخدمة، وتصغير أسماء الحقول.
+
+## التثبيت
+
+```bash
+npm install @intlayer/babel
+```
+
+## التصديرات
+
+استيراد:
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### الإضافات (Plugins)
+
+| الدالة / الفئة                 | الوصف                                                                                                                                                                           |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`   | إضافة Babel تستخرج المحتوى القابل للترجمة من ملفات المصدر وتُدرج hooks `useIntlayer` / `getIntlayer` تلقائيًا. مُصمَّمة للاستخدام مع Next.js وأدوات البناء المعتمدة على Babel.  |
+| `intlayerOptimizeBabelPlugin`  | إضافة Babel تُحوِّل استدعاءات `useIntlayer` و`getIntlayer` وتُعيد كتابة استيراداتها إلى استيرادات قواميس JSON مُحسَّنة (ثابتة أو ديناميكية أو عبر fetch).                       |
+| `intlayerPurgeBabelPlugin`     | إضافة Babel تُحلِّل ملفات المصدر وتُعيد كتابة ملفات JSON للقواميس المُجمَّعة لحذف الحقول غير المستخدمة (`build.purge`) أو إعادة تسميتها بأسماء مختصرة (`build.minify`).         |
+| `intlayerMinifyBabelPlugin`    | إضافة Babel تُعيد كتابة ملفات المصدر لاستخدام أسماء الحقول المختصرة المُعيَّنة أثناء مرحلة التصغير (مثلاً `content.title` ← `content.a`). تعتمد على `intlayerPurgeBabelPlugin`. |
+| `makeFieldRenameBabelPlugin`   | دالة مُنشِئة (factory) تُنتج إضافة Babel تُعيد تسمية وصولات حقول محتوى القاموس في ملفات المصدر وفق خريطة `dictionaryKeyToFieldRenameMap` الموجودة في `PruneContext`.            |
+| `makeUsageAnalyzerBabelPlugin` | دالة مُنشِئة تُنتج إضافة Babel تُحلِّل استخدام `useIntlayer` / `getIntlayer` في الكود المصدري وتُجمِّع بيانات استخدام الحقول في `PruneContext` المُشترك.                        |
+| `getSharedPruneContext`        | دالة مساعدة تُعيد كائن `PruneContext` المُشترك للمجلد الأساسي المُحدَّد، أو `null` إن لم يُهيَّأ بعد.                                                                           |
+
+---
+
+### دوال إعداد الإضافات
+
+| الدالة                     | الوصف                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | تُحمِّل إعداد Intlayer وتُعيد خيارات `ExtractPluginOptions` جاهزة للاستخدام مع `intlayerExtractBabelPlugin`.                        |
+| `getOptimizePluginOptions` | تُحمِّل إعداد Intlayer والقواميس المُجمَّعة وتُعيد خيارات `OptimizePluginOptions` جاهزة للاستخدام مع `intlayerOptimizeBabelPlugin`. |
+| `getPurgePluginOptions`    | تُحمِّل إعداد Intlayer وتُعيد خيارات `PurgePluginOptions` جاهزة للاستخدام مع `intlayerPurgeBabelPlugin`.                            |
+| `getMinifyPluginOptions`   | تُحمِّل إعداد Intlayer وتُعيد خيارات `MinifyPluginOptions` جاهزة للاستخدام مع `intlayerMinifyBabelPlugin`.                          |
+
+---
+
+### الأنواع
+
+| النوع                   | الوصف                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `CompilerMode`          | وضع المُجمِّع: `'dev'` للتطوير مع دعم HMR أو `'build'` لبناء الإنتاج.                                   |
+| `ExtractPluginOptions`  | خيارات `intlayerExtractBabelPlugin`: قائمة الملفات، الإعداد، callback `onExtract`، وغيرها.              |
+| `ExtractResult`         | نتيجة الاستخراج: مفتاح القاموس، مسار الملف، المحتوى، واللغة.                                            |
+| `OptimizePluginOptions` | خيارات `intlayerOptimizeBabelPlugin`: مسارات القواميس، وضع الاستيراد، خريطة الأوضاع لكل قاموس، إلخ.     |
+| `PurgePluginOptions`    | خيارات `intlayerPurgeBabelPlugin`: المجلد الأساسي، علامات purge/minify/optimize، قائمة ملفات المكوّنات. |
+| `MinifyPluginOptions`   | خيارات `intlayerMinifyBabelPlugin`: المجلد الأساسي، علامات minify/optimize/editorEnabled.               |
+| `PruneContext`          | الحالة المُشتركة بين إضافات التحليل والتنقية: خرائط استخدام الحقول، خرائط إعادة التسمية، إلخ.           |
+| `DictionaryFieldUsage`  | نتيجة استخدام الحقول لقاموس واحد: `Set<string>` أو `'all'` عند تعذُّر التحديد الساكن.                   |
+| `NestedRenameEntry`     | عقدة في شجرة إعادة التسمية: الاسم المختصر `shortName` وخريطة الأبناء `children`.                        |
+| `NestedRenameMap`       | مستوى واحد في شجرة إعادة التسمية: `Map<string, NestedRenameEntry>`.                                     |
+| `CompatCallerConfig`    | إعداد مُحلِّل استخدام مُتوافق لحزم الـ compat-adapter (اسم المُستدعي وخيارات المعالجة).                 |
+| `ScriptBlock`           | كتلة script مستخرجة من ملف SFC (Vue أو Svelte): المحتوى وإزاحتا البداية والنهاية.                       |
+
+---
+
+### الأدوات المساعدة
+
+| الدالة                            | الوصف                                                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | تُحوِّل رقمًا صحيحًا (ابتداءً من الصفر) إلى معرِّف أبجدي مختصر: `0 → 'a'`, `25 → 'z'`, `26 → 'aa'`, إلخ.                         |
+| `buildNestedRenameMapFromContent` | تبني `NestedRenameMap` بصورة مُتكرِّرة من قيمة محتوى قاموس مُجمَّع، مع احترام بنية عقد Intlayer (translation، enumeration، إلخ). |
+| `createPruneContext`              | تُنشئ كائن `PruneContext` فارغًا جديدًا مُهيَّأً بالقيم الافتراضية.                                                              |
+| `extractScriptBlocks`             | تستخرج كتل `<script>` من ملفات SFC (Vue / Svelte) للتحليل اللاحق بـ Babel.                                                       |
+| `BABEL_PARSER_OPTIONS`            | ثابت يُمثِّل خيارات مُحلِّل Babel تُغطي مجموعة الأُطر المدعومة (React/Vue/Svelte/Angular/…).                                     |
+| `INTLAYER_CALLER_NAMES`           | قائمة ثابتة بأسماء المُستدعِيين الأصلية لـ Intlayer: `['useIntlayer', 'getIntlayer']`.                                           |
+
+---
+
+## مثال على الاستخدام
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **ملاحظة:** يجب أن تُدرَج `intlayerPurgeBabelPlugin` **قبل** `intlayerMinifyBabelPlugin`، لأن الأخيرة تقرأ خريطة إعادة التسمية التي تبنيها الأولى. كما يجب أن تسبقهما معًا `intlayerOptimizeBabelPlugin` حتى تتمكّن من رؤية مفاتيح القاموس قبل إعادة كتابة استدعاءات `useIntlayer`.

package/docs/ar/packages/angular-intlayer/exports.md

@@ -14,9 +14,12 @@ slugs:
   - angular-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "إضافة الأداة المساعدة usePathname"
   - version: 8.0.0
     date: 2026-01-21
-    changes: "Unified documentation for all exports"
+    changes: "توحيد التوثيق لجميع الصادرات"
 author: aymericzip
 ---
 
@@ -46,15 +49,16 @@ import "angular-intlayer";
 
 ### الـ Hooks
 
-| الـ Hook               | الوصف                                                                                                 | المستند ذو الصلة |
-| ---------------------- | ----------------------------------------------------------------------------------------------------- | ---------------- |
-| `useIntlayer`          | مبنية على `useDictionary`، لكنها تحقن نسخة مُحسّنة من القاموس مأخوذة من التصريح المُولد.              | -                |
-| `useDictionary`        | يعالج الكائنات التي تشبه القواميس (مفتاح، محتوى). يعالج ترجمات `t()`، والتعدادات (enumerations)، إلخ. | -                |
-| `useDictionaryAsync`   | نفس عمل `useDictionary`، لكنه يتعامل مع القواميس غير المتزامنة (asynchronous).                        | -                |
-| `useDictionaryDynamic` | نفس عمل `useDictionary`، لكنه يتعامل مع القواميس الديناميكية (dynamic).                               | -                |
-| `useLocale`            | يعيد الـ locale الحالي ودالة لتعيينه.                                                                 | -                |
-| `useIntl`              | يعيد كائن Intl للـ locale الحالي.                                                                     | -                |
-| `useLoadDynamic`       | Hook لتحميل القواميس الديناميكية.                                                                     | -                |
+| الـ Hook               | الوصف                                                                                                 | المستند ذو الصلة                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`          | مبنية على `useDictionary`، لكنها تحقن نسخة مُحسّنة من القاموس مأخوذة من التصريح المُولد.              | -                                                                                                                     |
+| `useDictionary`        | يعالج الكائنات التي تشبه القواميس (مفتاح، محتوى). يعالج ترجمات `t()`، والتعدادات (enumerations)، إلخ. | -                                                                                                                     |
+| `useDictionaryAsync`   | نفس عمل `useDictionary`، لكنه يتعامل مع القواميس غير المتزامنة (asynchronous).                        | -                                                                                                                     |
+| `useDictionaryDynamic` | نفس عمل `useDictionary`، لكنه يتعامل مع القواميس الديناميكية (dynamic).                               | -                                                                                                                     |
+| `useLocale`            | إرجاع اللغة الحالية ووظيفة لتعيينها.                                                                  | -                                                                                                                     |
+| `usePathname`          | يُرجع المسار الحالي كـ `Signal<string>` مع إزالة جزء اللغة. يتفاعل مع `popstate` عبر `DestroyRef`.    | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/angular-intlayer/usePathname.md) |
+| `useIntl`              | إرجاع كائن Intl للغة الحالية.                                                                         | -                                                                                                                     |
+| `useLoadDynamic`       | Hook لتحميل القواميس الديناميكية.                                                                     | -                                                                                                                     |
 
 ### المكوّنات
 

package/docs/ar/packages/angular-intlayer/usePathname.md

@@ -0,0 +1,119 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: توثيق Hook usePathname | angular-intlayer
+description: تعرف على كيفية استخدام hook usePathname في حزمة angular-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Angular
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - angular-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "إضافة الأداة المساعدة usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "تهيئة السجل"
+author: aymericzip
+---
+
+# تكامل Angular: توثيق Hook `usePathname`
+
+يُرجع الـ hook `usePathname` مسار المتصفح الحالي مع إزالة جزء اللغة، كإشارة (Signal) من نوع `Signal<string>` في Angular. يُعد هذا مفيدًا لبناء تنقل (navigation) يعتمد على اللغة — على سبيل المثال، لتحديد عنصر التنقل النشط — دون الحاجة إلى إزالة بادئة اللغة يدويًا.
+
+## استيراد `usePathname` في Angular
+
+```typescript
+import { usePathname } from "angular-intlayer";
+```
+
+## نظرة عامة
+
+يقوم `usePathname` بقراءة `window.location.pathname`، ويزيل بادئة اللغة عبر `getPathWithoutLocale`، ويُحدّث الإشارة (signal) كلما أطلق المتصفح حدث `popstate` (التنقل للخلف/للأمام). يستخدم `DestroyRef` الخاص بـ Angular لتنظيف مستمع الحدث تلقائيًا عند تدمير المكون.
+
+## الاستخدام
+
+```typescript fileName="src/app/nav-item.component.ts"
+import { Component, input } from "@angular/core";
+import { usePathname } from "angular-intlayer";
+
+@Component({
+  standalone: true,
+  selector: "app-nav-item",
+  template: `
+    <a
+      [href]="href()"
+      [attr.aria-current]="pathname() === href() ? 'page' : null"
+    >
+      {{ label() }}
+    </a>
+  `,
+})
+export class NavItemComponent {
+  readonly href = input.required<string>();
+  readonly label = input.required<string>();
+
+  readonly pathname = usePathname();
+}
+```
+
+## القيمة المُرجعة
+
+| النوع            | الوصف                                                   |
+| ---------------- | ------------------------------------------------------- |
+| `Signal<string>` | إشارة Angular تحتوي على المسار الحالي بدون بادئة اللغة. |
+
+## السلوك
+
+- **إزالة اللغة**: يزيل جزء اللغة الأولي (مثل `/ar/dashboard` → `/dashboard`).
+- **تفاعلي**: يتم التحديث تلقائيًا عند أحداث `popstate` (تنقل المتصفح للخلف / للأمام).
+- **آمن لـ SSR**: يُرجع `""` عندما لا يكون `window` متاحًا.
+- **التنظيف**: يتم إزالة مستمع الحدث `popstate` عبر `DestroyRef.onDestroy` عند تدمير المكون المُضيف.
+
+## مثال
+
+```typescript fileName="src/app/sidebar.component.ts"
+import { Component } from "@angular/core";
+import { usePathname } from "angular-intlayer";
+
+@Component({
+  standalone: true,
+  selector: "app-sidebar",
+  template: `
+    <nav>
+      @for (link of links; track link.href) {
+        <a
+          [href]="link.href"
+          [style.font-weight]="pathname() === link.href ? 'bold' : 'normal'"
+        >
+          {{ link.label }}
+        </a>
+      }
+    </nav>
+  `,
+})
+export class SidebarComponent {
+  readonly links = [
+    { href: "/dashboard", label: "لوحة التحكم" },
+    { href: "/settings", label: "الإعدادات" },
+  ];
+
+  readonly pathname = usePathname();
+}
+```
+
+## مواضيع ذات صلة
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/angular-intlayer/exports.md) — اللغة الحالية + مبدل اللغة
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getPathWithoutLocale.md) — الأداة المساعدة الأساسية التي يستخدمها هذا الـ hook