@intlayer/docs 8.6.1 → 8.6.10

package/docs/ar/custom_domains.md

@@ -0,0 +1,250 @@
+---
+createdAt: 2026-04-02
+updatedAt: 2026-04-02
+title: نطاقات مخصصة (Custom Domains)
+description: تعرف على كيفية تكوين توجيه اللغات القائم على النطاق في Intlayer لخدمة لغات مختلفة من أسماء مضيفين مخصصة.
+keywords:
+  - نطاقات مخصصة
+  - توجيه النطاق
+  - التوجيه
+  - التدويل
+  - i18n
+slugs:
+  - doc
+  - concept
+  - custom_domains
+history:
+  - version: 8.5.0
+    date: 2026-04-02
+    changes: "إضافة توجيه اللغات القائم على النطاق عبر تكوين routing.domains."
+---
+
+# نطاقات مخصصة
+
+يدعم Intlayer توجيه اللغات القائم على النطاق، مما يسمح لك بتقديم لغات محددة من أسماء مضيفين مخصصة. على سبيل المثال، يمكن توجيه الزوار الصينيين إلى `intlayer.zh` بدلاً من `intlayer.org/zh`.
+
+## كيف يعمل
+
+تربط خريطة `domains` في `routing` كل لغة باسم مضيف. يستخدم Intlayer هذه الخريطة في مكانين:
+
+1. **توليد الرابط** (`getLocalizedUrl`): عندما تكون اللغة المستهدفة موجودة على نطاق _مختلف_ عن الصفحة الحالية، يتم إرجاع رابط مطلق (مثل `https://intlayer.zh/about`). عندما يتطابق كلا النطاقين، يتم إرجاع رابط نسبي (مثل `/fr/about`).
+2. **بروكسي الخادم** (Next.js و Vite): تتم إعادة توجيه الطلبات الواردة أو إعادة كتابتها بناءً على النطاق الذي تصل إليه.
+
+### النطاقات الحصرية مقابل المشتركة
+
+الفرق الرئيسي هو **الحصرية**:
+
+- **نطاق حصري** — لغة واحدة فقط ترتبط باسم المضيف هذا (مثل `zh → intlayer.zh`). النطاق نفسه يحدد اللغة، لذا لا يتم إضافة بادئة لغة إلى المسار. يخدم `https://intlayer.zh/about` المحتوى الصيني.
+- **نطاق مشترك** — ترتبط لغات متعددة بنفس اسم المضيف (مثل `en` و `fr` كلاهما يرتبطان بـ `intlayer.org`). يتم تطبيق التوجيه التقليدي القائم على البادئة. يخدم `intlayer.org/fr/about` المحتوى الفرنسي.
+
+## التكوين
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      Locales.CHINESE,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    mode: "prefix-no-default",
+    domains: {
+      // نطاق مشترك — en و fr يستخدمان توجيه البادئة على intlayer.org
+      en: "intlayer.org",
+      // نطاق حصري — zh لها اسم مضيف خاص بها، لا حاجة لبادئة /zh/
+      zh: "intlayer.zh",
+    },
+  },
+};
+
+export default config;
+```
+
+تستمر اللغات غير المدرجة في `domains` في استخدام توجيه البادئة القياسي دون أي تجاوز للنطاق.
+
+## توليد الرابط (URL Generation)
+
+يقوم `getLocalizedUrl` تلقائيًا بإنتاج نوع الرابط الصحيح بناءً على سياق الاستدعاء.
+
+### لغة في نفس النطاق (رابط نسبي)
+
+```ts
+// الصفحة الحالية: intlayer.org/about
+getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.org" });
+// ← "/fr/about"
+
+getLocalizedUrl("/about", "en", { currentDomain: "intlayer.org" });
+// ← "/about"  (اللغة الافتراضية، لا توجد بادئة)
+```
+
+### لغة في نطاق مختلف (رابط مطلق)
+
+```ts
+// الصفحة الحالية: intlayer.org/about
+getLocalizedUrl("/about", "zh", { currentDomain: "intlayer.org" });
+// ← "https://intlayer.zh/about"  (نطاق حصري، لا توجد بادئة /zh/)
+```
+
+### الخدمة من النطاق الخاص باللغة
+
+```ts
+// الصفحة الحالية: intlayer.zh/about
+getLocalizedUrl("/about", "zh", { currentDomain: "intlayer.zh" });
+// ← "/about"  (بالفعل على النطاق الصحيح — رابط نسبي)
+
+getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.zh" });
+// ← "https://intlayer.org/fr/about"  (رابط عبر النطاقات يعود إلى intlayer.org)
+```
+
+### الكشف التلقائي عن النطاق الحالي
+
+خيار `currentDomain` اختياري. عند حذفه، يقوم `getLocalizedUrl` بحله بهذا الترتيب:
+
+1. اسم المضيف لرابط إدخال مطلق (مثلاً `https://intlayer.org/about` ← `intlayer.org`).
+2. `window.location.hostname` في بيئات المتصفح.
+3. إذا لم يتوفر أي منهما (SSR بدون خيار صريح)، يتم إرجاع رابط نسبي للغات الموجودة على نفس النطاق ولا يتم إنتاج رابط مطلق — وهذا هو التراجع الآمن.
+
+```ts
+// المتصفح — window.location.hostname === 'intlayer.org'
+getLocalizedUrl("/about", "zh");
+// ← "https://intlayer.zh/about"  (تم اكتشافه تلقائيًا من النافذة)
+
+// من رابط مطلق — تم اكتشاف النطاق تلقائيًا
+getLocalizedUrl("https://intlayer.org/about", "zh");
+// ← "https://intlayer.zh/about"
+```
+
+### `getMultilingualUrls` مع النطاقات
+
+يستدعي `getMultilingualUrls` الدالة `getLocalizedUrl` لكل لغة، لذا فهو ينتج مزيجًا من الروابط النسبية والمطلقة اعتمادًا على نطاق المستدعي:
+
+```ts
+// currentDomain: 'intlayer.org'
+getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
+// {
+//   en: "/about",
+//   fr: "/fr/about",
+//   es: "/es/about",
+//   zh: "https://intlayer.zh/about",
+// }
+```
+
+هذه الروابط المطلقة جاهزة للاستخدام في وسوم `<link rel="alternate" hreflang="...">` لـ SEO.
+
+## سلوك البروكسي (Proxy Behaviour)
+
+### Next.js
+
+يتعامل وسيط `intlayerProxy` مع توجيه النطاق تلقائيًا. أضفه إلى ملف `middleware.ts`:
+
+```typescript fileName="middleware.ts"
+export { intlayerProxy as default } from "next-intlayer/proxy";
+
+export const config = {
+  matcher: "/((?!api|static|assets|robots|sitemap|.*\\..*|_next).*)",
+};
+```
+
+**إعادة التوجيه (Redirect)** — يصل الطلب إلى النطاق الخطأ لبادئة لغة معينة:
+
+```
+GET intlayer.org/zh/about
+← 301 https://intlayer.zh/about
+```
+
+**إعادة الكتابة (Rewrite)** — يصل الطلب إلى النطاق الحصري للغة بدون بادئة:
+
+```
+GET intlayer.zh/about
+← إعادة الكتابة إلى /zh/about  (توجيه Next.js الداخلي فقط، يظل الرابط نظيفًا)
+```
+
+### Vite
+
+يطبق ملحق `intlayerProxy` الخاص بـ Vite نفس المنطق أثناء التطوير:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayerProxy } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerProxy()],
+});
+```
+
+> **ملاحظة**: في التطوير المحلي، تكون عادةً على `localhost` ن لذا ستشير عمليات إعادة التوجيه عبر النطاقات إلى النطاقات المباشرة بدلاً من منفذ محلي آخر. استخدم تجاوز ملف hosts (مثلاً `127.0.0.1 intlayer.zh`) أو بروكسي عكسي إذا كنت بحاجة إلى اختبار توجيه النطاقات المتعددة محليًا.
+
+## مبدل اللغة (Locale Switcher)
+
+يتعامل خطاف `useLocale` من `next-intlayer` مع التنقل المدرك للنطاق تلقائيًا. عندما ينتقل المستخدم إلى لغة على نطاق مختلف، يقوم الخطاف بتنقل كامل للصفحة (`window.location.href`) بدلاً من دفع موجه جانب العميل، لأن موجه Next.js لا يمكنه تجاوز الأصول (origins).
+
+```tsx fileName="components/LocaleSwitcher.tsx"
+"use client";
+
+import { useLocale } from "next-intlayer";
+
+export const LocaleSwitcher = () => {
+  const { availableLocales, locale, setLocale } = useLocale();
+
+  return (
+    <ul>
+      {availableLocales.map((localeEl) => (
+        <li key={localeEl}>
+          <button
+            onClick={() => setLocale(localeEl)}
+            aria-current={localeEl === locale ? "true" : undefined}
+          >
+            {l.toUpperCase()}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+};
+```
+
+لا يلزم تكوين إضافي — يكتشف `useLocale` داخليًا `window.location.hostname` ويقرر بين `router.replace` (نفس النطاق) و `window.location.href` (عبر النطاقات).
+
+## SEO: روابط `hreflang` البديلة
+
+يشيع استخدام التوجيه القائم على النطاق مع `hreflang` لإخبار محركات البحث بالرابط الذي يجب أرشفته لكل لغة. استخدم `getMultilingualUrls` لإنشاء المجموعة الكاملة من الروابط البديلة:
+
+```tsx fileName="app/[locale]/layout.tsx"
+import { getMultilingualUrls } from "intlayer";
+import type { Metadata } from "next";
+
+export const generateMetadata = (): Metadata => {
+  const alternates = getMultilingualUrls("/", {
+    currentDomain: process.env.NEXT_PUBLIC_DOMAIN, // مثلًا "intlayer.org"
+  });
+
+  return {
+    alternates: {
+      languages: alternates,
+    },
+  };
+};
+```
+
+ينتج عن هذا:
+
+```html
+<link rel="alternate" hreflang="en" href="https://intlayer.org/" />
+<link rel="alternate" hreflang="fr" href="https://intlayer.org/fr/" />
+<link rel="alternate" hreflang="es" href="https://intlayer.org/es/" />
+<link rel="alternate" hreflang="zh" href="https://intlayer.zh/" />
+```
+
+## الأدوات الأساسية (Core Utilities)
+
+| الأداة                                            | الوصف                                                                                   |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `getLocalizedUrl(url, locale, { currentDomain })` | يرجع رابطًا نسبيًا أو مطلقًا اعتمادًا على ما إذا كانت اللغة المستهدفة في النطاق الحالي. |
+| `getMultilingualUrls(url, { currentDomain })`     | يرجع خريطة روابط محلية مفهرسة باللغة، تجمع بين الروابط النسبية والمطلقة حسب الحاجة.     |
+| `getPrefix(locale, { domains })`                  | يرجع بادئة فارغة للغات ذات النطاق الحصري، وبادئة عادية في حالات أخرى.                   |

package/docs/ar/intlayer_with_tanstack+solid.md

@@ -16,6 +16,7 @@ slugs:
   - doc
   - environment
   - tanstack-start
+  - solid
 applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-solid-template
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
@@ -162,59 +163,45 @@ export default defineConfig({
 
 ### الخطوة 5: إنشاء التخطيط الجذري (Root Layout)
 
-قم بتكوين التخطيط الجذري الخاص بك لدعم التدويل باستخدام `useMatches` لاكتشاف اللغة الحالية وتعيين سمات `lang` و `dir` على وسم `html`.
+قم بتكوين التخطيط الجذري الخاص بك لدعم التدويل باستخدام `useParams` لاكتشاف اللغة الحالية وتعيين سمات `lang` و `dir` على وسم `html`.
 
 ```tsx fileName="src/routes/__root.tsx"
 import {
   HeadContent,
-  Outlet,
   Scripts,
   createRootRouteWithContext,
-  useMatches,
 } from "@tanstack/solid-router";
-import { TanStackRouterDevtools } from "@tanstack/solid-router-devtools";
 import { HydrationScript } from "solid-js/web";
-import { Suspense } from "solid-js";
+import { Suspense, type ParentComponent } from "solid-js";
 import { IntlayerProvider } from "solid-intlayer";
-import { defaultLocale, getHTMLTextDir, type Locale } from "intlayer";
+import { defaultLocale, getHTMLTextDir } from "intlayer";
+import { Route as LocaleRoute } from "./{-$locale}/route";
 
 export const Route = createRootRouteWithContext()({
   shellComponent: RootComponent,
 });
 
-type Params = {
-  locale: Locale;
-};
-
-function RootComponent() {
-  const matches = useMatches();
-
-  // محاولة العثور على اللغة في معلمات أي مطابقة نشطة
-  // يفترض هذا أنك تستخدم الجزء الديناميكي "/{-$locale}" في شجرة المسارات الخاصة بك
-  const locale =
-    (
-      matches().find((match) => match.routeId === "/{-$locale}/")
-        ?.params as Params
-    )?.locale ?? defaultLocale;
+const RootComponent: ParentComponent = (props) => {
+  const params = LocaleRoute.useParams();
+  const locale = params()?.locale ?? defaultLocale;
 
   return (
     <html dir={getHTMLTextDir(locale)} lang={locale}>
       <head>
         <HydrationScript />
+        <HeadContent />
       </head>
       <body>
-        <HeadContent />
         <IntlayerProvider locale={locale}>
           <Suspense>
-            <Outlet />
-            <TanStackRouterDevtools />
+            {props.children}
           </Suspense>
         </IntlayerProvider>
         <Scripts />
       </body>
     </html>
   );
-}
+};
 ```
 
 ### الخطوة 6: إنشاء تخطيط اللغة (اختياري)
@@ -458,18 +445,12 @@ export default LocaleSwitcher;
 
 ### الخطوة 11: إدارة سمات HTML
 
-كما رأيت في الخطوة 5، يمكنك إدارة سمات `lang` و `dir` لوسم `html` باستخدام `useMatches` في المكون الجذري الخاص بك. يضمن ذلك تعيين السمات الصحيحة على كل من الخادم والعميل.
+كما رأيت في الخطوة 5، يمكنك إدارة سمات `lang` و `dir` لوسم `html` باستخدام `useParams` في المكون الجذري الخاص بك. يضمن ذلك تعيين السمات الصحيحة على كل من الخادم والعميل.
 
 ```tsx fileName="src/routes/__root.tsx"
 const RootComponent: ParentComponent = (props) => {
-  const matches = useMatches();
-
-  // محاولة العثور على اللغة في معلمات أي مطابقة نشطة
-  const locale =
-    (
-      matches().find((match) => match.routeId === "/{-$locale}/")
-        ?.params as Params
-    )?.locale ?? defaultLocale;
+  const params = LocaleRoute.useParams();
+  const locale = params()?.locale ?? defaultLocale;
 
   return (
     <html dir={getHTMLTextDir(locale)} lang={locale}>

package/docs/ar/intlayer_with_tanstack.md

@@ -182,31 +182,41 @@ export default config;
 
 ### الخطوة 5: إنشاء التخطيط الجذري
 
-قم بتكوين التخطيط الجذري الخاص بك لدعم التدويل باستخدام `useMatches` للكشف عن اللغة الحالية وتعيين سمات `lang` و `dir` على علامة `html`.
+قم بتكوين التخطيط الجذري الخاص بك لدعم التدويل باستخدام `useParams` للكشف عن اللغة الحالية وتعيين سمات `lang` و `dir` على علامة `html`.
 
 ```tsx fileName="src/routes/__root.tsx"
 import {
   createRootRouteWithContext,
   HeadContent,
-  Outlet,
   Scripts,
-  useMatches,
 } from "@tanstack/react-router";
 import { defaultLocale, getHTMLTextDir } from "intlayer";
 import { type ReactNode } from "react";
 import { IntlayerProvider } from "react-intlayer";
+import { Route as LocaleRoute } from "./{-$locale}/route";
 
 export const Route = createRootRouteWithContext<{}>()({
+  head: () => ({
+    meta: [
+      {
+        charSet: "utf-8",
+      },
+      {
+        content: "width=device-width, initial-scale=1",
+        name: "viewport",
+      },
+      {
+        title: "TanStack Start Starter",
+      },
+    ],
+  }),
+
   shellComponent: RootDocument,
 });
 
 function RootDocument({ children }: { children: ReactNode }) {
-  const matches = useMatches();
-
-  // حاول العثور على اللغة في معلمات أي مطابقة نشطة
-  // يفترض هذا أنك تستخدم الجزء الديناميكي "/{-$locale}" في شجرة المسارات الخاصة بك
-  const localeRoute = matches.find((match) => match.routeId === "/{-$locale}");
-  const locale = localeRoute?.params?.locale ?? defaultLocale;
+  const params = LocaleRoute.useParams();
+  const locale = params?.locale ?? defaultLocale;
 
   return (
     <html dir={getHTMLTextDir(locale)} lang={locale}>
@@ -214,7 +224,9 @@ function RootDocument({ children }: { children: ReactNode }) {
         <HeadContent />
       </head>
       <body>
-        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+        <IntlayerProvider locale={locale}>
+          {children}
+        </IntlayerProvider>
         <Scripts />
       </body>
     </html>
@@ -557,15 +569,12 @@ export const LocaleSwitcher: FC = () => {
 
 ### الخطوة 11: إدارة سمات HTML
 
-كما رأينا في الخطوة 5، يمكنك إدارة سمات `lang` و `dir` لعلامة `html` باستخدام `useMatches` في مكونك الجذري. يضمن هذا تعيين السمات الصحيحة على الخادم والعميل.
+كما رأينا في الخطوة 5، يمكنك إدارة سمات `lang` و `dir` لعلامة `html` باستخدام `useParams` في مكونك الجذري. يضمن هذا تعيين السمات الصحيحة على الخادم والعميل.
 
 ```tsx fileName="src/routes/__root.tsx"
 function RootDocument({ children }: { children: ReactNode }) {
-  const matches = useMatches();
-
-  // حاول العثور على اللغة في معلمات أي مطابقة نشطة
-  const localeRoute = matches.find((match) => match.routeId === "/{-$locale}");
-  const locale = localeRoute?.params?.locale ?? defaultLocale;
+  const params = LocaleRoute.useParams();
+  const locale = params?.locale ?? defaultLocale;
 
   return (
     <html dir={getHTMLTextDir(locale)} lang={locale}>