@intlayer/docs 9.5.5 → 9.5.7

package/docs/ar/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-09-19
+updatedAt: 2026-09-21
 title: "تدويل Astro - الدليل الكامل لترجمة تطبيقك"
 description: "لا مزيد من i18next. دليل 2026 لبناء تطبيق Astro متعدد اللغات (i18n). ترجم باستخدام وكلاء الذكاء الاصطناعي وحسّن حجم الحزمة وتحسين محركات البحث والأداء."
 keywords:
@@ -160,6 +160,29 @@ bun add intlayer astro-intlayer
 </Step>
 <Step number={2} title="تهيئة مشروعك">
 
+### البنية
+
+في هذه البنية، يقوم تكامل `intlayer()` المسجل في `astro.config.ts` ببناء القواميس الخاصة بك وإضافة برمجية وسيطة (middleware) تحدد لغة كل طلب وتوفرها عبر `Astro.locals.intlayer`. تتواجد الصفحات تحت مقطع `src/pages/[...locale]/`، بحيث يتم تقديم اللغة الافتراضية بدون بادئة ويحصل كل خيار لغة آخر على عنوان URL مخصص له. تقرأ ملفات `.astro` المحتوى باستخدام خطافات `useIntlayer` / `useLocale` الخاصة بـ `astro-intlayer`، وتوضع تصريحات المحتوى جنباً إلى جنب مع مكوناتك في `src/`.
+
+```bash
+.
+├── src
+│   ├── app.content.tsx               # App content declaration
+│   ├── components
+│   │   └── LocaleSwitcher.astro      # Locale switcher component
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page (rest param also serves the default locale)
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() integration
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### التكوين
+
 أنشئ ملف تكوين لتحديد لغات تطبيقك:
 
 ```typescript fileName="intlayer.config.ts"
@@ -400,7 +423,7 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 ```
 
 > **ملاحظة حول الاستمرارية:**
-> يحفظ `setLocale` من `useLocale` من جانب العميل تفضيل لغة المستخدم في ملف تعريف ارتباط. يسمح هذا للوسيط البرمجي Intlayer بتذكر الاختيار وإعادة توجيه المستخدم تلقائياً إلى لغته المفضلة في الزيارات المستقبلية.
+> يحفظ `setLocale` من `useLocale` من جانب العميل تفضيل لغة المستخدم في ملف تعريف ارتباط. يتيح ذلك لـ Intlayer تذكر الاختيار وإعادة توجيه المستخدم تلقائياً إلى لغته المفضلة في الزيارات المستقبلية: تتم إعادة توجيه الصفحات المعروضة عند الطلب (باستخدام محول مع `output: 'server'` أو `prerender = false`) بواسطة وسيط Intlayer البرمجي قبل إرسال أي HTML، بينما تتم إعادة توجيه الصفحات المعروضة مسبقاً، والتي تُقدم كملفات ثابتة، بواسطة سكريبت صغير يحقنه التكامل في كل صفحة. عيّن `routing.enableProxy` إلى `false` لإيقاف تشغيل كليهما. في `astro dev`، يتم تجاهل ملف تعريف الارتباط كمصدر لإعادة التوجيه ما لم يتم تعيين `routing.enableProxy` إلى `true`، حتى لا يختطف ملف تعريف ارتباط قديم الصفحات التي تعمل عليها.
 >
 > **التوافق المتبادل بين الخادم والعميل:**
 > يحل `astro-intlayer` إلى خطافات الخادم في الواجهة الأمامية (بقراءة `Astro.locals`) وإلى خطافات العميل لـ `vanilla-intlayer` في كتل `<script>` والجزر (islands)، بنفس الأسماء وهيكل المحتوى. يعمل `setLocale` و `onChange` على العميل فقط، استدعِ `installIntlayer()` هناك مرة واحدة لتهيئة مخزن العميل. يكشف `astro-intlayer/client` نقطة إدخال العميل بشكل صريح.
@@ -412,9 +435,9 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 
 #### خريطة الموقع (Sitemap)
 
-Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.
+يأتي Intlayer مع مولد خريطة موقع مدمج لمساعدتك في إنشاء خريطة موقع لتطبيقك بسهولة. يتعامل مع المسارات المترجمة ويضيف البيانات الوصفية اللازمة لمحركات البحث.
 
-> The Intlayer generated sitemap supports the `xhtml:link` namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., `/about`, `/about?lang=fr`, and `/about?lang=es`). This ensures search engines correctly index and serve the right language version to the right audience.
+> تدعم خريطة الموقع المُنشأة من قِبل Intlayer مساحة الأسماء `xhtml:link` (Hreflang XML Extensions). على عكس مولدات خرائط الموقع الافتراضية التي تُدرج عناوين URL الخام فقط، ينشئ Intlayer تلقائياً الروابط ثنائية الاتجاه المطلوبة بين جميع إصدارات الصفحة باللغات المختلفة (على سبيل المثال، `/about` و `/about?lang=fr` و `/about?lang=es`). هذا يضمن أن محركات البحث تفهرس بشكل صحيح وتقدم النسخة الصحيحة من اللغة للجمهور المناسب.
 
 أنشئ `src/pages/sitemap.xml.ts` لإنشاء خريطة موقع تتضمن جميع مساراتك المترجمة.
 
@@ -427,10 +450,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -471,20 +494,21 @@ export const GET: APIRoute = ({ site }) => {
 
 استمر في بناء تطبيقك باستخدام إطار العمل الذي تختاره.
 
-- Intlayer + React: [Intlayer مع React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+react.md)
-- Intlayer + Vue: [Intlayer مع Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+vue.md)
-- Intlayer + Svelte: [Intlayer مع Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+svelte.md)
-- Intlayer + Solid: [Intlayer مع Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+solid.md)
-- Intlayer + Preact: [Intlayer مع Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+preact.md)
+- Intlayer + React: [Intlayer مع React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_astro_react.md)
+- Intlayer + Vue: [Intlayer مع Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_astro_vue.md)
+- Intlayer + Svelte: [Intlayer مع Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_astro_svelte.md)
+- Intlayer + Solid: [Intlayer مع Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_astro_solid.md)
+- Intlayer + Preact: [Intlayer مع Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_astro_preact.md)
+- Intlayer + Lit: [Intlayer مع Lit](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_astro_lit.md)
 </Step>
 
-<Step number={15} title="Extract the content of your components" isOptional={true}>
+<Step number={15} title="استخراج محتوى مكوناتك" isOptional={true}>
 
-If you have an existing codebase, transforming thousands of files can be time-consuming.
+إذا كان لديك كود برمجي موجود بالفعل، فقد يستغرق تحويل آلاف الملفات وقتاً طويلاً.
 
-To ease this process, Intlayer propose a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/extract.md) to transform your components and extract the content.
+لتسهيل هذه العملية، يقترح Intlayer [مترجمًا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compiler.md) / [مستخرجًا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/extract.md) لتحويل مكوناتك واستخراج المحتوى.
 
-To set it up, you can add a `compiler` section in your `intlayer.config.ts` file:
+لإعداده، يمكنك إضافة قسم `compiler` في ملف `intlayer.config.ts` الخاص بك:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { type IntlayerConfig } from "intlayer";
@@ -524,7 +548,7 @@ export default config;
 <Tabs>
  <Tab value='Extract command'>
 
-Run the extractor to transform your components and extract the content
+قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى
 
 ```bash packageManager="npm"
 npx intlayer extract
@@ -545,21 +569,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+قم ببناء تطبيقك لتحويل مكوناتك واستخراج المحتوى
 
 ```bash packageManager="npm"
 npm run build # Or npm run dev

package/docs/ar/intlayer_with_astro_lit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-06-23
+updatedAt: 2026-09-21
 title: "تدويل Astro + Lit - الدليل الكامل لترجمة تطبيقك"
 description: "لا مزيد من i18next. دليل 2026 لبناء تطبيق Astro + Lit متعدد اللغات (i18n). ترجم باستخدام وكلاء الذكاء الاصطناعي وحسّن حجم الحزمة وتحسين محركات البحث والأداء."
 keywords:
@@ -20,6 +20,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "استخدام خطافات useIntlayer / useLocale لـ astro-intlayer في صفحة Astro"
   - version: 8.9.0
     date: 2026-05-04
     changes: "تحديث استخدام واجهة برمجة تطبيقات useIntlayer في Solid للوصول المباشر إلى الخصائص"
@@ -151,7 +154,7 @@ bun add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
   الحزمة الأساسية التي توفر أدوات i18n لإدارة التكوين، الترجمات، [تعريف المحتوى](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dictionary/content_file.md)، التحويل، و[أوامر CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/index.md).
 
 - **astro-intlayer**
-  تتضمن إضافة تكامل Astro لربط Intlayer بـ [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production)، بالإضافة إلى وسيط (middleware) لاكتشاف لغة المستخدم المفضلة، وإدارة ملفات تعريف الارتباط (cookies)، والتعامل مع إعادة توجيه الروابط.
+  يتضمن ملحق تكامل Astro لدمج Intlayer مع [حازم Vite](https://vite.dev/guide/why.html#why-bundle-for-production)، ووسيطاً برمجياً يحدد لغة كل طلب في `Astro.locals.intlayer`، وخطافات `useIntlayer` / `useDictionary` / `useLocale`. يحل نفس مسار الاستيراد إلى تنفيذ الخادم في واجهة `.astro` وإلى تنفيذ العميل (المدعوم بـ `vanilla-intlayer`) في كتل `<script>`.
 
 - **lit**
   حزمة Lit الأساسية لبناء مكونات ويب (Web Components) سريعة وخفيفة.
@@ -165,6 +168,30 @@ bun add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
 </Step>
 <Step number={2} title="تهيئة مشروعك">
 
+### البنية
+
+في هذه البنية، يقوم تكامل `intlayer()` المسجل في `astro.config.ts` ببناء القواميس الخاصة بك وإضافة برمجية وسيطة (middleware) تحدد لغة كل طلب وتوفرها عبر `Astro.locals.intlayer`. تتواجد الصفحات تحت مقطع `src/pages/[...locale]/`، بحيث يتم تقديم اللغة الافتراضية بدون بادئة ويحصل كل خيار لغة آخر على عنوان URL مخصص له. تقرأ ملفات `.astro` المحتوى باستخدام خطافات `useIntlayer` / `useLocale` الخاصة بـ `astro-intlayer` للعرض على جانب الخادم، وتتلقى جزيرة Lit (`src/components/lit/LitDemo.ts`) اللغة المكتشفة من الخادم كخاصية (prop) وتمررها إلى `lit-intlayer` للجزء التفاعلي. وتوضع تصريحات المحتوى جنباً إلى جنب مع مكوناتك في `src/`.
+
+```bash
+.
+├── src
+│   ├── components
+│   │   └── lit
+│   │       ├── app.content.ts        # App content declaration
+│   │       └── LitDemo.ts            # Lit custom element (content + locale switcher)
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page mounting the custom element
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() and lit() integrations
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### التكوين
+
 أنشئ ملف تكوين لتحديد لغات تطبيقك:
 
 ```typescript fileName="intlayer.config.ts"
@@ -246,29 +273,34 @@ export default litDemoContent;
 </Step>
 <Step number={5} title="استخدام المحتوى في Astro">
 
-يمكنك استهلاك القواميس مباشرة في ملفات `.astro` الخاصة بك باستخدام المساعدين الأساسيين المصدرين من `intlayer`. يجب عليك أيضًا إضافة ميتا داتا SEO (مثل hreflang وروابط canonical) لكل صفحة. يتم استيراد عناصر Lit المخصصة عبر وسم `<script>` للعميل وتوضع في المتن (body).
+استخدم قواميسك في ملفات `.astro` باستخدام الخطافات المصدرة بواسطة `astro-intlayer`. تشترك هذه الخطافات في نفس تواقيع روابط إطار العمل: يُرجع `useIntlayer("key")` محتوى القاموس ويُرجع `useLocale()` اللغة الحالية، دون الحاجة إلى تمرير أي وسيطات.
+
+تأتي اللغة من الوسيط البرمجي `astro-intlayer`، والذي يسجله التكامل تلقائياً قبل `src/middleware.ts` الخاص بك. يحدد الوسيط اللغة لكل طلب، بدءاً من بادئة عنوان URL، ثم اللغة المحفوظة بواسطة العميل (ملف تعريف الارتباط أو الترويسة)، ثم `Accept-Language`، ويخزنها في `Astro.locals.intlayer`. تستخدم الصفحات المعروضة مسبقاً عنوان URL فقط، حيث يتم عرضها مرة واحدة لكل زائر.
+
+يجب عليك أيضاً إضافة بيانات تعريف SEO مثل hreflang والروابط الأساسية (canonical) إلى كل صفحة. يتم بعد ذلك استيراد عنصر Lit المخصص عبر `<script>` من جانب العميل ووضعه في النص الأساسي (body).
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 
 export const getStaticPaths = () => {
-  return localeMap(({ locale }) => ({
-    params: { locale: getPrefix(locale).localePrefix },
+  return defaultLocale.map((locale) => ({
+    params: { locale },
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { greeting } = getIntlayer("lit-demo", locale);
+// اللغة المحددة بواسطة الوسيط البرمجي (مثال: /ar/about -> 'ar')
+const { locale } = useLocale();
+
+// محتوى قاموس 'lit-demo' لتلك اللغة
+const { greeting } = useIntlayer("lit-demo");
 ---
 
 <!doctype html>
@@ -327,6 +359,8 @@ const { greeting } = getIntlayer("lit-demo", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> يعرض `Astro.locals.intlayer` أيضاً `locale` و `defaultLocale` و `availableLocales` للوسطاء البرمجيين ونقاط النهاية الخاصة بك. مرر لغة أو محدداً كوسيط ثانٍ (`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`) لتجاوز لغة الطلب لاستدعاء واحد.
+
 > **ملاحظة حول إعداد التوجيه:**
 > تعتمد بنية الدليل التي تستخدمها على إعداد `middleware.routing` في `intlayer.config.ts`:
 >
@@ -468,9 +502,9 @@ override render() {
 
 #### خريطة الموقع (Sitemap)
 
-Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.
+يأتي Intlayer مع مولد خريطة موقع مدمج لمساعدتك في إنشاء خريطة موقع لتطبيقك بسهولة. يتعامل مع المسارات المترجمة ويضيف البيانات الوصفية اللازمة لمحركات البحث.
 
-> The Intlayer generated sitemap supports the `xhtml:link` namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., `/about`, `/about?lang=fr`, and `/about?lang=es`). This ensures search engines correctly index and serve the right language version to the right audience.
+> تدعم خريطة الموقع المُنشأة من قِبل Intlayer مساحة الأسماء `xhtml:link` (Hreflang XML Extensions). على عكس مولدات خرائط الموقع الافتراضية التي تُدرج عناوين URL الخام فقط، ينشئ Intlayer تلقائياً الروابط ثنائية الاتجاه المطلوبة بين جميع إصدارات الصفحة باللغات المختلفة (على سبيل المثال، `/about` و `/about?lang=fr` و `/about?lang=es`). هذا يضمن أن محركات البحث تفهرس بشكل صحيح وتقدم النسخة الصحيحة من اللغة للجمهور المناسب.
 
 أنشئ `src/pages/sitemap.xml.ts` لإنشاء خريطة موقع تتضمن جميع مساراتك المترجمة.
 
@@ -483,10 +517,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -523,13 +557,13 @@ export const GET: APIRoute = ({ site }) => {
 ```
 
 </Step>
-<Step number={15} title="Extract the content of your components" isOptional={true}>
+<Step number={15} title="استخراج محتوى مكوناتك" isOptional={true}>
 
-If you have an existing codebase, transforming thousands of files can be time-consuming.
+إذا كان لديك كود برمجي موجود بالفعل، فقد يستغرق تحويل آلاف الملفات وقتاً طويلاً.
 
-To ease this process, Intlayer propose a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/extract.md) to transform your components and extract the content.
+لتسهيل هذه العملية، يقترح Intlayer [مترجمًا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compiler.md) / [مستخرجًا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/extract.md) لتحويل مكوناتك واستخراج المحتوى.
 
-To set it up, you can add a `compiler` section in your `intlayer.config.ts` file:
+لإعداده، يمكنك إضافة قسم `compiler` في ملف `intlayer.config.ts` الخاص بك:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { type IntlayerConfig } from "intlayer";
@@ -569,7 +603,7 @@ export default config;
 <Tabs>
  <Tab value='Extract command'>
 
-Run the extractor to transform your components and extract the content
+قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى
 
 ```bash packageManager="npm"
 npx intlayer extract
@@ -590,21 +624,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+قم ببناء تطبيقك لتحويل مكوناتك واستخراج المحتوى
 
 ```bash packageManager="npm"
 npm run build # Or npm run dev

package/docs/ar/intlayer_with_astro_preact.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-06-23
+updatedAt: 2026-09-21
 title: "تدويل Astro + Preact - الدليل الكامل لترجمة تطبيقك"
 description: "لا مزيد من i18next. دليل 2026 لبناء تطبيق Astro + Preact متعدد اللغات (i18n). ترجم باستخدام وكلاء الذكاء الاصطناعي وحسّن حجم الحزمة وتحسين محركات البحث والأداء."
 keywords:
@@ -19,6 +19,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "استخدام خطافات useIntlayer / useLocale لـ astro-intlayer في صفحة Astro"
   - version: 8.9.0
     date: 2026-05-04
     changes: "تحديث استخدام واجهة برمجة تطبيقات useIntlayer في Solid للوصول المباشر إلى الخصائص"
@@ -150,7 +153,7 @@ bun add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
   الحزمة الأساسية التي توفر أدوات i18n لإدارة التكوين، الترجمات، [تعريف المحتوى](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dictionary/content_file.md)، التحويل، و[أوامر CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/index.md).
 
 - **astro-intlayer**
-  تتضمن إضافة تكامل Astro لربط Intlayer بـ [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production)، بالإضافة إلى وسيط (middleware) لاكتشاف لغة المستخدم المفضلة، وإدارة ملفات تعريف الارتباط (cookies)، والتعامل مع إعادة توجيه الروابط.
+  يتضمن ملحق تكامل Astro لدمج Intlayer مع [حازم Vite](https://vite.dev/guide/why.html#why-bundle-for-production)، ووسيطاً برمجياً يحدد لغة كل طلب في `Astro.locals.intlayer`، وخطافات `useIntlayer` / `useDictionary` / `useLocale`. يحل نفس مسار الاستيراد إلى تنفيذ الخادم في واجهة `.astro` وإلى تنفيذ العميل (المدعوم بـ `vanilla-intlayer`) في كتل `<script>`.
 
 - **preact**
   حزمة Preact الأساسية - بديل سريع وخفيف لـ React.
@@ -164,6 +167,31 @@ bun add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
 </Step>
 <Step number={2} title="تهيئة مشروعك">
 
+### البنية
+
+في هذه البنية، يقوم تكامل `intlayer()` المسجل في `astro.config.ts` ببناء القواميس الخاصة بك وإضافة برمجية وسيطة (middleware) تحدد لغة كل طلب وتوفرها عبر `Astro.locals.intlayer`. تتواجد الصفحات تحت مقطع `src/pages/[...locale]/`، بحيث يتم تقديم اللغة الافتراضية بدون بادئة ويحصل كل خيار لغة آخر على عنوان URL مخصص له. تقرأ ملفات `.astro` المحتوى باستخدام خطافات `useIntlayer` / `useLocale` الخاصة بـ `astro-intlayer` للعرض على جانب الخادم، وتتلقى جزيرة Preact (`src/components/preact/PreactIsland.tsx`) اللغة المكتشفة من الخادم كخاصية (prop) وتمررها إلى `preact-intlayer` للجزء التفاعلي. وتوضع تصريحات المحتوى جنباً إلى جنب مع مكوناتك في `src/`.
+
+```bash
+.
+├── src
+│   ├── app.content.tsx               # App content declaration
+│   ├── components
+│   │   └── preact
+│   │       ├── LocaleSwitcher.tsx    # Locale switcher rendered inside the island
+│   │       └── PreactIsland.tsx      # Preact island wrapping the tree in IntlayerProvider
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page mounting the island
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() and preact() integrations
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### التكوين
+
 أنشئ ملف تكوين لتحديد لغات تطبيقك:
 
 ```typescript fileName="intlayer.config.ts"
@@ -243,30 +271,35 @@ export default appContent;
 </Step>
 <Step number={5} title="استخدام المحتوى في Astro">
 
-يمكنك استهلاك القواميس مباشرة في ملفات `.astro` الخاصة بك باستخدام المساعدين الأساسيين المصدرين من `intlayer`. يجب عليك أيضًا إضافة ميتا داتا SEO (مثل hreflang وروابط canonical) لكل صفحة وتقديم جزيرة Preact للمحتوى التفاعلي في جانب العميل.
+استخدم قواميسك في ملفات `.astro` باستخدام الخطافات المصدرة بواسطة `astro-intlayer`. تشترك هذه الخطافات في نفس تواقيع روابط إطار العمل: يُرجع `useIntlayer("key")` محتوى القاموس ويُرجع `useLocale()` اللغة الحالية، دون الحاجة إلى تمرير أي وسيطات.
+
+تأتي اللغة من الوسيط البرمجي `astro-intlayer`، والذي يسجله التكامل تلقائياً قبل `src/middleware.ts` الخاص بك. يحدد الوسيط اللغة لكل طلب، بدءاً من بادئة عنوان URL، ثم اللغة المحفوظة بواسطة العميل (ملف تعريف الارتباط أو الترويسة)، ثم `Accept-Language`، ويخزنها في `Astro.locals.intlayer`. تستخدم الصفحات المعروضة مسبقاً عنوان URL فقط، حيث يتم عرضها مرة واحدة لكل زائر.
+
+يجب عليك أيضاً إضافة بيانات تعريف SEO مثل hreflang والروابط الأساسية (canonical) إلى كل صفحة وتضمين جزيرة Preact للمحتوى التفاعلي من جانب العميل.
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 import { PreactIsland } from "../../components/preact/PreactIsland";
 
 export const getStaticPaths = () => {
-  return localeMap(({ locale }) => ({
-    params: { locale: getPrefix(locale).localePrefix },
+  return defaultLocale.map((locale) => ({
+    params: { locale },
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { title } = getIntlayer("app", locale);
+// اللغة المحددة بواسطة الوسيط البرمجي (مثال: /ar/about -> 'ar')
+const { locale } = useLocale();
+
+// محتوى قاموس 'app' لتلك اللغة
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -322,6 +355,8 @@ const { title } = getIntlayer("app", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> يعرض `Astro.locals.intlayer` أيضاً `locale` و `defaultLocale` و `availableLocales` للوسطاء البرمجيين ونقاط النهاية الخاصة بك. مرر لغة أو محدداً كوسيط ثانٍ (`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`) لتجاوز لغة الطلب لاستدعاء واحد.
+
 > **ملاحظة حول إعداد التوجيه:**
 > تعتمد بنية الدليل التي تستخدمها على إعداد `middleware.routing` في `intlayer.config.ts`:
 >
@@ -423,9 +458,9 @@ export const LocaleSwitcher: FunctionalComponent = () => {
 
 #### خريطة الموقع (Sitemap)
 
-Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.
+يأتي Intlayer مع مولد خريطة موقع مدمج لمساعدتك في إنشاء خريطة موقع لتطبيقك بسهولة. يتعامل مع المسارات المترجمة ويضيف البيانات الوصفية اللازمة لمحركات البحث.
 
-> The Intlayer generated sitemap supports the `xhtml:link` namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., `/about`, `/about?lang=fr`, and `/about?lang=es`). This ensures search engines correctly index and serve the right language version to the right audience.
+> تدعم خريطة الموقع المُنشأة من قِبل Intlayer مساحة الأسماء `xhtml:link` (Hreflang XML Extensions). على عكس مولدات خرائط الموقع الافتراضية التي تُدرج عناوين URL الخام فقط، ينشئ Intlayer تلقائياً الروابط ثنائية الاتجاه المطلوبة بين جميع إصدارات الصفحة باللغات المختلفة (على سبيل المثال، `/about` و `/about?lang=fr` و `/about?lang=es`). هذا يضمن أن محركات البحث تفهرس بشكل صحيح وتقدم النسخة الصحيحة من اللغة للجمهور المناسب.
 
 أنشئ `src/pages/sitemap.xml.ts` لإنشاء خريطة موقع تتضمن جميع مساراتك المترجمة.
 
@@ -438,10 +473,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -478,13 +513,13 @@ export const GET: APIRoute = ({ site }) => {
 ```
 
 </Step>
-<Step number={15} title="Extract the content of your components" isOptional={true}>
+<Step number={15} title="استخراج محتوى مكوناتك" isOptional={true}>
 
-If you have an existing codebase, transforming thousands of files can be time-consuming.
+إذا كان لديك كود برمجي موجود بالفعل، فقد يستغرق تحويل آلاف الملفات وقتاً طويلاً.
 
-To ease this process, Intlayer propose a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/extract.md) to transform your components and extract the content.
+لتسهيل هذه العملية، يقترح Intlayer [مترجمًا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compiler.md) / [مستخرجًا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/cli/extract.md) لتحويل مكوناتك واستخراج المحتوى.
 
-To set it up, you can add a `compiler` section in your `intlayer.config.ts` file:
+لإعداده، يمكنك إضافة قسم `compiler` في ملف `intlayer.config.ts` الخاص بك:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { type IntlayerConfig } from "intlayer";
@@ -524,7 +559,7 @@ export default config;
 <Tabs>
  <Tab value='Extract command'>
 
-Run the extractor to transform your components and extract the content
+قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى
 
 ```bash packageManager="npm"
 npx intlayer extract
@@ -545,21 +580,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+قم ببناء تطبيقك لتحويل مكوناتك واستخراج المحتوى
 
 ```bash packageManager="npm"
 npm run build # Or npm run dev