@intlayer/docs 9.1.3 → 9.3.0

package/docs/ar/intlayer_CMS.md

@@ -247,6 +247,158 @@ bun x intlayer dictionary push -d my-first-dictionary-key --env production
 
 بعد ذلك، ستتمكن من رؤية وإدارة قاموسك في [نظام إدارة محتوى Intlayer](https://app.intlayer.org/content).
 
+## الوصول البرمجي باستخدام SDK `@intlayer/api`
+
+بالإضافة إلى واجهة سطر الأوامر والمحرر المرئي، يأتي Intlayer مع SDK مكتوب بشكل آمن من حيث النوع في حزمة [`@intlayer/api`](https://www.npmjs.com/package/@intlayer/api). يتيح لك التعامل مع نظام إدارة المحتوى كـ **قاعدة بيانات محتوى بدون رأس**: يمكنك جلب المشاريع وجلب القواميس، وتحديثها مباشرة من تطبيقك الخاص أو البرامج النصية أو خط أنابيب CI.
+
+يتعامل SDK مع المصادقة من أجلك. طالما أن `clientId` و `clientSecret` متاحة (في تكوين Intlayer أو البيئة)، فإنه يحصل على رمز OAuth2 للوصول وينعشه تلقائياً ويوقع كل طلب.
+
+### التثبيت
+
+```bash packageManager="npm"
+npm install @intlayer/api
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/api
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/api
+```
+
+```bash packageManager="bun"
+bun add @intlayer/api
+```
+
+### كيفية عملها: المصادق + نقاط النهاية
+
+تم تقسيم SDK إلى **استيرادين منفصلين** عن قصد، للحفاظ على حجم حزمتك صغيرًا:
+
+1. `createIntlayerCMS` — ينشئ **مصادقًا** خفيف الوزن. يحمل فقط بيانات الاعتماد والرمز المميز للوصول المُدار؛ لا يعرف شيئًا عن أي مجال محدد.
+2. `dictionaryEndpoint`, `projectEndpoint`, … — **محررات نقاط النهاية** لكل مجال، يتم استيراد كل منها من مسارها الخاص (`@intlayer/api/dictionary`, `@intlayer/api/project`, …). تمرر المصادق إلى نقطة النهاية التي تحتاجها.
+
+لأن كل نقطة نهاية يتم استيرادها بشكل منفصل، تتضمن حزمتك فقط المجالات التي تستخدمها فعليًا — استيراد `dictionaryEndpoint` لا يسحب أبدًا المشروع أو الذكاء الاصطناعي أو أي عميل مجال آخر.
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+
+// التكوين اختياري: عند حذفه، يتم قراءة بيانات الاعتماد من
+// `@intlayer/config/built`، الذي يحل متغيرات البيئة INTLAYER_CLIENT_ID و
+// INTLAYER_CLIENT_SECRET.
+export const cmsAuthenticator = createIntlayerCMS();
+```
+
+> [!WARNING]
+> بيانات اعتماد CMS (`clientId` / `clientSecret`) تمنح **حق الوصول للكتابة** إلى محتواك. لا تنشئ المصادق أبدًا إلا على **الجانب الخادم** (إجراءات الخادم، معالجات المسارات، البرامج النصية، CI). لا تستورده أبدًا في الكود من جانب العميل أو تعرض بيانات اعتمادك للمتصفح.
+
+إذا فضلت عدم الاعتماد على تكوين وقت البناء، مرر بيانات الاعتماد بشكل صريح:
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+
+export const cmsAuthenticator = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    // اختياري، للخوادم الذاتية الاستضافة:
+    // backendURL: process.env.INTLAYER_BACKEND_URL,
+  },
+});
+```
+
+> احصل على بيانات اعتمادك بإنشاء مفتاح وصول جديد في [لوحة معلومات Intlayer - المشاريع](https://app.intlayer.org/projects).
+
+### جلب المشاريع
+
+```typescript fileName="projects.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { projectEndpoint } from "@intlayer/api/project";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// قائمة المشاريع التي يمكن الوصول إليها باستخدام بيانات اعتمادك
+const { data: projects } =
+  await projectEndpoint(cmsAuthenticator).getProjects();
+
+// قراءة رؤى التوطين المجمعة للمشروع المحدد
+const { data: insights } =
+  await projectEndpoint(cmsAuthenticator).getProjectInsights();
+```
+
+### جلب القواميیس
+
+```typescript fileName="read-dictionaries.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// قائمة بكل قاموس بعید من المشروع
+const { data: dictionaries } =
+  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();
+
+// أو الحصول على قاموس واحد حسب المفتاح
+const { data: dictionary } = await dictionaryEndpoint(
+  cmsAuthenticator
+).getDictionary("my-first-dictionary-key");
+```
+
+### دفع وتحديث القواميس
+
+استخدم نظام إدارة المحتوى (CMS) كقاعدة بيانات لكتابة المحتوى مرة أخرى:
+
+```typescript fileName="write-dictionaries.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// إنشاء قاموس جديد
+await dictionaryEndpoint(cmsAuthenticator).addDictionary({
+  key: "my-first-dictionary-key",
+  content: { title: "Hello world" },
+});
+
+// Upsert مجموعة من القواميس (إنشاء أو تحديثها في استدعاء واحد)
+await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([
+  { key: "home", content: { title: "Home" } },
+  { key: "about", content: { title: "About" } },
+]);
+
+// تحديث قاموس موجود
+await dictionaryEndpoint(cmsAuthenticator).updateDictionary({
+  id: "<dictionary-id>",
+  key: "home",
+  content: { title: "Updated title" },
+});
+```
+
+> نصيحة: أعد استخدام نقطة النهاية المرتبطة لتجنب تكرار نفسك:
+>
+> ```typescript codeFormat="typescript"
+> const dictionary = dictionaryEndpoint(cmsAuthenticator);
+> await dictionary.pushDictionaries([myDictionary]);
+> const { data } = await dictionary.getDictionaries();
+> ```
+
+### استخراج طريقة واحدة
+
+كل طريقة endpoint مصادق عليها بالفعل وقائمة بذاتها (تحمل معالجة الرمز الخاص بها)، لذا يمكنك استخراج واحدة وتمريرها حوله — على سبيل المثال لحقنها كتبعية:
+
+```typescript fileName="push.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const dictionary = dictionaryEndpoint(createIntlayerCMS());
+
+// مصادق عليه بالفعل — ينعش الرمز تلقائياً في كل استدعاء
+export const pushDictionaries = dictionary.pushDictionaries;
+
+// الاستخدام
+await pushDictionaries([{ key: "home", content: { title: "Home" } }]);
+```
+
 ## التزامن الحي
 
 يتيح التزامن الحي لتطبيقك عكس تغييرات محتوى نظام إدارة المحتوى أثناء وقت التشغيل. لا حاجة لإعادة البناء أو إعادة النشر. عند التمكين، يتم بث التحديثات إلى خادم التزامن الحي الذي يقوم بتحديث القواميس التي يقرأها تطبيقك.

package/docs/ar/intlayer_with_angular_21.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-04-18
 updatedAt: 2026-05-31
-title: "تدويل Angular 21 - الدليل الكامل لترجمة تطبيقك"
-description: "لا مزيد من i18next. دليل 2026 لبناء تطبيق Angular 21 متعدد اللغات (i18n). ترجم باستخدام وكلاء الذكاء الاصطناعي وحسّن حجم الحزمة وتحسين محركات البحث والأداء."
+title: "تدويل Angular 22 - الدليل الكامل لترجمة تطبيقك"
+description: "لا مزيد من i18next. دليل 2026 لبناء تطبيق Angular 22 متعدد اللغات (i18n). ترجم باستخدام وكلاء الذكاء الاصطناعي وحسّن حجم الحزمة وتحسين محركات البحث والأداء."
 keywords:
   - تدويل
   - وثائق
@@ -13,8 +13,8 @@ slugs:
   - doc
   - environment
   - angular
-applicationTemplate: https://github.com/aymericzip/intlayer-angular-21-template
-applicationShowcase: https://intlayer-angular-21-template.vercel.app/
+applicationTemplate: https://github.com/aymericzip/intlayer-angular-22-template
+applicationShowcase: https://intlayer-angular-22-template.vercel.app/
 history:
   - version: 8.9.0
     date: 2026-05-04
@@ -31,7 +31,7 @@ history:
 author: aymericzip
 ---
 
-# ترجم موقع Angular 21 (Vite) الخاص بك باستخدام Intlayer | التدويل (i18n)
+# ترجم موقع Angular 22 (Vite) الخاص بك باستخدام Intlayer | التدويل (i18n)
 
 ## جدول المحتويات
 
@@ -77,7 +77,7 @@ author: aymericzip
   <Tab label="الرمز" value="code">
 
 <iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-angular-21-template?file=intlayer.config.ts"
+  src="https://ide.intlayer.org/aymericzip/intlayer-angular-22-template?file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo CodeSandbox - كيفية تدويل تطبيقك باستخدام Intlayer"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -88,7 +88,7 @@ author: aymericzip
   <Tab label="عرض تجريبي" value="demo">
 
 <iframe
-  src="https://intlayer-angular-21-template.vercel.app/"
+  src="https://intlayer-angular-22-template.vercel.app/"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo - intlayer-angular-template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -98,7 +98,7 @@ author: aymericzip
   </Tab>
 </Tabs>
 
-راجع [قالب التطبيق](https://github.com/aymericzip/intlayer-angular-21-template) على GitHub.
+راجع [قالب التطبيق](https://github.com/aymericzip/intlayer-angular-22-template) على GitHub.
 
 <Steps>
 
@@ -186,7 +186,7 @@ export default config;
 
 <Step number={3} title="دمج Intlayer في تكوين Angular الخاص بك">
 
-لدمج Intlayer مع Angular CLI، تحتاج إلى استخدام باني مخصص (custom builder). يفترض هذا الدليل أنك تستخدم Vite/esbuild (الافتراضي لمشاريع Angular 21).
+لدمج Intlayer مع Angular CLI، تحتاج إلى استخدام باني مخصص (custom builder). يفترض هذا الدليل أنك تستخدم Vite/esbuild (الافتراضي لمشاريع Angular 22).
 
 أولاً، قم بتعديل `angular.json` الخاص بك لاستخدام باني esbuild المخصص. قم بتحديث تكوينات `build` و `serve`:
 

package/docs/ar/intlayer_with_nextjs_14.md

@@ -24,34 +24,7 @@ history:
 author: aymericzip
 ---
 
-# ترجم Next.js 14 and App Router باستخدام Intlayer | التدويل (i18n)
-
-<Tabs defaultTab="code">
-  <Tab label="كود" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-next-14-template?file=intlayer.config.ts"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - Intlayer"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-  <Tab label="تجربة" value="demo">
-
-<iframe
-  src="https://intlayer-next-14-template.vercel.app"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="تجربة - intlayer-next-14-template"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
-انظر [Template Application](https://github.com/aymericzip/intlayer-next-14-template) على GitHub.
+# ترجمة موقع Next.js 14 و App Router الخاص بك باستخدام Intlayer | Internationalization (i18n)
 
 ## جدول المحتويات
 

package/docs/ar/intlayer_with_nextjs_15.md

@@ -31,39 +31,7 @@ history:
 author: aymericzip
 ---
 
-# ترجم Next.js 15 باستخدام Intlayer | التدويل (i18n)
-
-<Tabs defaultTab="video">
-  <Tab label="فيديو" value="video">
-
-<iframe title="Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
-
-  </Tab>
-  <Tab label="كود" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-next-15-template?file=intlayer.config.ts"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - Intlayer"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-  <Tab label="تجربة" value="demo">
-
-<iframe
-  src="https://next-15-intlayer-template-xt83.vercel.app"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="تجربة - intlayer-next-15-template"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
-شاهد [قالب التطبيق](https://github.com/aymericzip/intlayer-next-15-template) على GitHub.
+# ترجمة موقع Next.js 15 الخاص بك باستخدام Intlayer | Internationalization (i18n)
 
 ## جدول المحتويات
 

package/docs/ar/intlayer_with_react_router_v7_fs_routes.md

@@ -165,99 +165,56 @@ app/
 - `_index` - مسار الفهرس (يتم عرضه في مسار العنصر الأب)
 - `.` (نقطة) - فاصل مقاطع المسار (مثال: `($locale).about` → `/:locale?/about`)
 
-## دليل خطوة بخطوة لإعداد Intlayer في تطبيق React Router v7 مع مسارات قائمة على نظام الملفات
+#### مكون التخطيط
 
-<Tabs defaultTab="video">
-  <Tab label="Video" value="video">
-
-<iframe title="How to translate an React Router v7 (File-System Routes) app using Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/dS9L7uJeak4?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
-
-  </Tab>
-  <Tab label="Code" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-react-router-v7-template?file=intlayer.config.ts"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-  <Tab label="تجربة" value="demo">
-
-<iframe
-  src="https://intlayer-react-router-v7.vercel.app"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="تجربة - intlayer-react-router-v7-template"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
-See [Application Template](https://github.com/aymericzip/intlayer-react-router-v7-template) on GitHub.
-
-قم بإنشاء ملف تكوين لتكوين لغات تطبيقك:
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { type IntlayerConfig, Locales } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    defaultLocale: Locales.ENGLISH, // اللغة الافتراضية
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], // اللغات المدعومة
-  },
-};
-
-export default config;
-```
-
-> من خلال ملف التكوين هذا، يمكنك إعداد عناوين URL محلية، إعادة توجيه الوسيط، أسماء ملفات تعريف الارتباط، موقع وامتداد إعلانات المحتوى الخاصة بك، تعطيل سجلات Intlayer في وحدة التحكم، والمزيد. للحصول على قائمة كاملة بالمعلمات المتاحة، راجع [توثيق التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md).
-
-<Steps>
-
-<Step number={3} title="دمج Intlayer في تكوين Vite الخاص بك">
-
-أضف مكون intlayer الإضافي إلى تكوينك:
+```tsx fileName="app/root.tsx"
+import { getLocaleFromPath } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+import {
+  isRouteErrorResponse,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+  useLoaderData,
+} from "react-router";
 
-```typescript fileName="vite.config.ts"
-import { reactRouter } from "@react-router/dev/vite";
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
+import type { Route } from "./+types/root";
 
-export default defineConfig({
-  plugins: [reactRouter(), intlayer()],
-});
-```
+import "./app.css";
 
-> يتم استخدام مكون Vite الإضافي `intlayer()` لدمج Intlayer مع Vite. يضمن بناء ملفات إعلان المحتوى ويراقبها في وضع التطوير. كما يحدد متغيرات بيئة Intlayer داخل تطبيق Vite. بالإضافة إلى ذلك، يوفر أسماء مستعارة لتحسين الأداء.
+// ... كود App و links و ErrorBoundary دون تغيير
 
-</Step>
+export async function loader({ request }: Route.LoaderArgs) {
+  const locale = getLocaleFromPath(request.url);
 
-<Step number={4} title="تكوين مسارات React Router v7">
-
-قم بإعداد تكوين التوجيه الخاص بك مع مسارات مدركة للغة:
+  return { locale };
+}
 
-```typescript fileName="app/routes.ts"
-typescript fileName="app/routes.ts"
-import { layout, route, type RouteConfig } from "@react-router/dev/routes";
+export function Layout({
+  children,
+}: { children: React.ReactNode } & Route.ComponentProps) {
+  const data = useLoaderData<typeof loader>();
+  const { locale } = data ?? {};
 
-export default [
-  layout("routes/layout.tsx", [
-    route("/:lang?", "routes/page.tsx"), // الصفحة الرئيسية المحلية
-    route("/:lang?/about", "routes/about/page.tsx"), // صفحة حول المحلية
-  ]),
-] satisfies RouteConfig;
+  return (
+    <html lang={locale}>
+      <head>
+        <meta charSet="utf-8" />
+        <meta content="width=device-width, initial-scale=1" name="viewport" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
 ```
 
-</Step>
-
-<Step number={5} title="إنشاء مكونات التخطيط">
-
-قم بإعداد التخطيط الجذري والتخطيطات الخاصة باللغة:
-
 #### التخطيط الجذري
 
 ```tsx fileName="app/routes/layout.tsx"