@intlayer/docs 7.0.4-canary.0 → 7.0.4

package/blog/ar/intlayer_with_react-i18next.md

@@ -1,346 +1,124 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer وreact-i18next
-description: قارن بين React باستخدام react-i18next و Intlayer
+updatedAt: 2025-10-29
+title: كيفية أتمتة ترجمات JSON الخاصة بـ react-i18next باستخدام Intlayer
+description: أتمتة ترجمات JSON الخاصة بك باستخدام Intlayer و react-i18next لتعزيز التدويل في تطبيقات React.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - التدويل
-  - التوثيق
-  - Next.js
-  - JavaScript
+  - i18n
+  - مدونة
   - React
+  - JavaScript
+  - TypeScript
+  - إدارة المحتوى
 slugs:
   - blog
   - intlayer-with-react-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: التغيير إلى مكون syncJSON
 ---
 
-# React Internationalization (i18n) with react-i18next and Intlayer
-
-## Overview
-
-- **Intlayer** يساعدك في إدارة الترجمة عبر **ملفات إعلان المحتوى على مستوى المكون**.
-- **react-i18next** هو دمج شائع لـ React مع **i18next** يقدم وظائف مثل `useTranslation` لجلب السلاسل المحلية في مكوناتك.
-
-عندما يتم دمجها، يمكن لـ Intlayer **تصدير** القواميس بتنسيق **i18next-compatible JSON** بحيث يمكن لـ react-i18next **استهلاكها** في وقت التشغيل.
-
-## Why Use Intlayer with react-i18next?
-
-ملفات إعلان المحتوى الخاصة بـ **Intlayer** تقدم تجربة مطور أفضل لأنها:
-
-1. **مرنة في مكان الملف**  
-   ضع كل ملف إعلان محتوى بجانب المكون الذي يحتاجه. تسمح لك هذه البنية بالحفاظ على الترجمات متواجدة بجوار بعضها البعض، مما يمنع الترجمات اليتيمة عند نقل المكونات أو حذفها.
-
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # ملف إعلان المحتوى
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # ملف إعلان المحتوى
-               └── index.mjx
-   ```
-
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # ملف إعلان المحتوى
-               └── index.cjx
-   ```
-
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # ملف إعلان المحتوى
-               └── index.jsx
-   ```
-
-2. **ترجمات مركزة**  
-   يجمع ملف إعلان محتوى واحد جميع الترجمات اللازمة لمكون، مما يجعل من السهل اكتشاف الترجمات الناقصة.  
-   مع TypeScript، ستحصل حتى على أخطاء في وقت الترجمة إذا كانت الترجمات مفقودة.
-
-## Installation
-
-في مشروع Create React App، قم بتثبيت هذه الاعتمادات:
-
-```bash
-# مع npm
-npm install intlayer react-i18next i18next i18next-resources-to-backend
-```
+# كيفية أتمتة ترجمات JSON الخاصة بـ react-i18next باستخدام Intlayer
 
-```bash
-# مع yarn
-yarn add intlayer react-i18next i18next i18next-resources-to-backend
-```
+## ما هو Intlayer؟
 
-```bash
-# مع pnpm
-pnpm add intlayer react-i18next i18next i18next-resources-to-backend
-```
+**Intlayer** هي مكتبة تدويل مبتكرة ومفتوحة المصدر مصممة لمعالجة أوجه القصور في حلول i18n التقليدية. تقدم نهجًا حديثًا لإدارة المحتوى في تطبيقات React.
 
-### What Are These Packages?
+اطلع على مقارنة ملموسة مع react-i18next في منشور مدونتنا [react-i18next مقابل react-intl مقابل Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ar/react-i18next_vs_react-intl_vs_intlayer.md).
 
-- **intlayer** – واجهة سطر الأوامر والمكتبة الأساسية لإدارة تكوينات i18n، وإعلانات المحتوى، وبناء مخارج القواميس.
-- **react-intlayer** – دمج خاص بـ React مع Intlayer، يوفر بشكل ملحوظ بعض النصوص لأتمتة بناء القواميس.
-- **react-i18next** – مكتبة دمج خاصة بـ React لـ i18next، تشمل وظيفة `useTranslation`.
-- **i18next** – الإطار الأساسي لمعالجة الترجمة.
-- **i18next-resources-to-backend** – واجهة خلفية لـ i18next تستورد الموارد JSON ديناميكيًا.
+## لماذا الجمع بين Intlayer و react-i18next؟
 
-## Configuring Intlayer to Export i18next Dictionaries
+بينما يوفر Intlayer حلاً ممتازًا مستقلاً لـ i18n (راجع دليل التكامل مع React الخاص بنا [React integration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_vite+react.md))، قد ترغب في دمجه مع react-i18next لأسباب عدة:
 
-قم بإنشاء (أو تحديث) `intlayer.config.ts` في جذر مشروعك:
+1. **قاعدة الشيفرة الحالية**: لديك تنفيذ قائم لـ react-i18next وترغب في الترحيل تدريجيًا إلى تجربة المطور المحسنة التي يقدمها Intlayer.
+2. **متطلبات قديمة**: مشروعك يتطلب التوافق مع الإضافات أو سير العمل الحالي لـ react-i18next.
+3. **ألفة الفريق**: فريقك مرتاح لاستخدام react-i18next لكنه يرغب في إدارة محتوى أفضل.
 
-```typescript title="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
+**لهذا، يمكن تنفيذ Intlayer كمحول لـ react-i18next للمساعدة في أتمتة ترجمات JSON الخاصة بك في واجهة الأوامر أو خطوط أنابيب CI/CD، واختبار ترجماتك، والمزيد.**
 
-const config: IntlayerConfig = {
-  internationalization: {
-    // أضف كما تريد من اللغات
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    // أخبر Intlayer لإنشاء JSON متوافق مع i18next
-    dictionaryOutput: ["i18next"],
+يوضح هذا الدليل كيفية الاستفادة من نظام إعلان المحتوى المتفوق في Intlayer مع الحفاظ على التوافق مع react-i18next.
 
-    // اختر دليلًا لمخرجات الموارد المولدة
-    // سيتم إنشاء هذا المجلد إذا لم يكن موجودًا بعد.
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+## جدول المحتويات
 
-export default config;
-```
-
-> **ملاحظة**: إذا كنت لا تستخدم TypeScript، يمكنك إنشاء هذا الملف كـ `.cjs`، `.mjs`، أو `.js` (انظر [مستندات Intlayer](https://intlayer.org/ar/doc/concept/configuration) للحصول على التفاصيل).
-
-## Building the i18next Resources
-
-بمجرد أن تكون إعلانات المحتوى موجودة (في القسم التالي)، قم بتشغيل **أمر بناء Intlayer**:
-
-```bash
-# مع npm
-npx run intlayer build
-```
-
-```bash
-# مع yarn
-yarn intlayer build
-```
+<TOC/>
 
-```bash
-# مع pnpm
-pnpm intlayer build
-```
+## دليل خطوة بخطوة لإعداد Intlayer مع react-i18next
 
-> سيولد هذا موارد i18next الخاصة بك داخل دليل `./i18next/resources` بشكل افتراضي.
+### الخطوة 1: تثبيت التبعيات
 
-قد يبدو الناتج النموذجي كما يلي:
+قم بتثبيت الحزم اللازمة:
 
-```bash
-.
-└── i18next
-    └── resources
-       ├── en
-       │   └── my-content.json
-       ├── fr
-       │   └── my-content.json
-       └── es
-           └── my-content.json
+```bash packageManager="npm"
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-حيث يتم استخدام كل مفتاح إعلان **Intlayer** كـ **مساحة اسم i18next** (على سبيل المثال، `my-content.json`).
-
-## Importing Dictionaries into Your react-i18next Configuration
-
-لتحميل هذه الموارد ديناميكيًا في وقت التشغيل، استخدم [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend). على سبيل المثال، قم بإنشاء ملف `i18n.ts` (أو `.js`) في مشروعك:
-
-```typescript title="i18n.ts"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  // مكون إضافي react-i18next
-  .use(initReactI18next)
-  // تحميل الموارد ديناميكيًا
-  .use(
-    resourcesToBackend((language: string, namespace: string) => {
-      // قم بضبط مسار الاستيراد إلى دليل الموارد الخاص بك
-      return import(`../i18next/resources/${language}/${namespace}.json`);
-    })
-  )
-  // تهيئة i18next
-  .init({
-    // اللغة الاحتياطية
-    fallbackLng: "en",
-
-    // يمكنك إضافة خيارات إعداد i18next الأخرى هنا، انظر:
-    // https://www.i18next.com/overview/configuration-options
-  });
-
-export default i18next;
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```javascript title="i18n.js"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  .use(initReactI18next)
-  .use(
-    resourcesToBackend(
-      (language, namespace) =>
-        import(`../i18next/resources/${language}/${namespace}.json`)
-    )
-  )
-  .init({
-    fallbackLng: "en",
-  });
-
-export default i18next;
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-ثم، في ملف **الجذر** أو **الفهرس** الخاص بك (مثل `src/index.tsx`)، قم باستيراد إعداد `i18n` هذا **قبل** عرض `App`:
+**وصف الحزم:**
 
-```typescript
-import React from "react";
-import ReactDOM from "react-dom/client";
-// تهيئة i18n قبل أي شيء آخر
-import "./i18n";
-import App from "./App";
+- **intlayer**: المكتبة الأساسية لإدارة التدويل، إعلان المحتوى، والبناء
+- **@intlayer/sync-json-plugin**: إضافة لتصدير إعلانات محتوى Intlayer إلى صيغة JSON المتوافقة مع react-i18next
 
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
+### الخطوة 2: تنفيذ إضافة Intlayer لتغليف JSON
 
-## Creating and Managing Your Dictionarys
+قم بإنشاء ملف تكوين Intlayer لتعريف اللغات المدعومة لديك:
 
-يستخرج Intlayer الترجمات من "ملفات إعلان المحتوى" الموجودة في أي مكان ضمن `./src` (بشكل افتراضي).  
-إليك مثال بسيط في TypeScript:
+**إذا كنت تريد أيضًا تصدير قواميس JSON لـ react-i18next**، أضف إضافة `syncJSON`:
 
-```typescript title="src/components/MyComponent/MyComponent.content.ts"
-import { t, type Dictionary } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-const content = {
-  // سيكون "المفتاح" مساحة اسم i18next الخاصة بك (مثل "my-component")
-  key: "my-component",
-  content: {
-    // كل مكالمة "t" هي عقدة ترجمة منفصلة
-    heading: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-    description: t({
-      en: "My i18n description text...",
-      fr: "Ma description en i18n...",
-      es: "Mi descripción en i18n...",
-    }),
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
   },
-} satisfies Dictionary;
-
-export default content;
-```
-
-إذا كنت تفضل JSON أو `.cjs` أو `.mjs`، راجع [مستندات Intlayer](https://intlayer.org/ar/doc/concept/content).
-
-> بشكل افتراضي، تتطابق إعلانات المحتوى الصحيحة مع نمط امتداد الملف:
-
-> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
-
-## Using the Translations in React Components
-
-بعد **بناء** موارد Intlayer الخاصة بك وتكوين react-i18next، يمكنك استخدام وظيفة `useTranslation` من **react-i18next** مباشرة.  
-على سبيل المثال:
-
-```tsx title="src/components/MyComponent/MyComponent.tsx"
-import type { FC } from "react";
-import { useTranslation } from "react-i18next";
-
-/**
- * "namespace" i18next هو المفتاح من Intlayer في "MyComponent.content.ts"
- * لذلك سنمرر "my-component" إلى useTranslation().
- */
-const MyComponent: FC = () => {
-  const { t } = useTranslation("my-component");
-
-  return (
-    <div>
-      <h1>{t("heading")}</h1>
-      <p>{t("description")}</p>
-    </div>
-  );
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
-export default MyComponent;
+export default config;
 ```
 
-> لاحظ أن دالة `t` تشير إلى **المفاتيح** داخل JSON الذي تم إنشاؤه. بالنسبة لإدخال محتوى Intlayer المسمى `heading`، ستستخدم `t("heading")`.
-
-## Optional: Integrate with Create React App Scripts (CRACO)
+إضافة `syncJSON` ستقوم تلقائيًا بتغليف JSON. ستقرأ وتكتب ملفات JSON دون تغيير بنية المحتوى.
 
-يوفر **react-intlayer** نهجًا يعتمد على CRACO للتكوينات المخصصة وبناء خادم التطوير. إذا كنت ترغب في دمج خطوة بناء Intlayer بسلاسة، يمكنك:
+إذا كنت تريد جعل ملفات JSON تتعايش مع ملفات إعلان محتوى intlayer (`.content` files)، فإن Intlayer سيتبع هذه الطريقة:
 
-1. **تثبيت react-intlayer** (إذا لم تقم بذلك):
-   ```bash
-   npm install react-intlayer --save-dev
-   ```
-2. **تعديل نصوص `package.json` الخاصة بك** لاستخدام نصوص `react-intlayer`:
+    1. تحميل كل من ملفات JSON وملفات إعلان المحتوى وتحويلها إلى قاموس intlayer.
+    2. إذا كانت هناك تعارضات بين ملفات JSON وملفات إعلان المحتوى، سيقوم Intlayer بدمج جميع القواميس. وذلك يعتمد على أولوية الإضافات، وأولوية ملف إعلان المحتوى (كلها قابلة للتكوين).
 
-   ```jsonc
-   "scripts": {
-     "start": "react-intlayer start",
-     "build": "react-intlayer build",
-     "transpile": "intlayer build"
-   }
-   ```
+إذا تم إجراء تغييرات باستخدام CLI لترجمة JSON، أو باستخدام نظام إدارة المحتوى (CMS)، سيقوم Intlayer بتحديث ملف JSON بالترجمات الجديدة.
 
-   > تعتمد نصوص `react-intlayer` على [CRACO](https://craco.js.org/). يمكنك أيضًا تنفيذ إعداد خاص بك استنادًا إلى مكون Intlayer craco. [انظر المثال هنا](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+للاطلاع على مزيد من التفاصيل حول إضافة `syncJSON`، يرجى الرجوع إلى [توثيق إضافة syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/plugins/sync-json.md).
 
-الآن، عند تشغيل `npm run build` أو `yarn build` أو `pnpm build`، يتم تفعيل كل من بناء Intlayer وCRA.
+## تكوين Git
 
-## TypeScript Configuration
+يوصى بتجاهل ملفات Intlayer التي يتم إنشاؤها تلقائيًا:
 
-يوفر **Intlayer** **تعريفات نوعية تلقائية** لمحتوياتك. لضمان أن TypeScript يأخذها بعين الاعتبار، أضف **`types`** (أو `types` إذا قمت بتكوينها بشكل مختلف) إلى مصفوفة **include** في `tsconfig.json` الخاصة بك:
-
-```json5 title="tsconfig.json"
-{
-  "compilerOptions": {
-    // ...
-  },
-  "include": ["src", "types"],
-}
+```plaintext fileName=".gitignore"
+# تجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer
+.intlayer
 ```
 
-> سيتيح ذلك لـ TypeScript استنتاج شكل الترجمات لديك للحصول على إكمال أفضل للأكواد واكتشاف الأخطاء.
+يمكن إعادة إنشاء هذه الملفات أثناء عملية البناء الخاصة بك ولا تحتاج إلى الالتزام بها في نظام التحكم في الإصدارات.
 
-## Git Configuration
+### إضافة VS Code
 
-يوصى بـ **تجاهل** الملفات والمجلدات المولدة تلقائيًا من Intlayer. أضف هذا السطر إلى `.gitignore`:
-
-```plaintext
-# تجاهل الملفات التي تم إنشاؤها بواسطة Intlayer
-.intlayer
-i18next
-```
+لتحسين تجربة المطور، قم بتثبيت **إضافة Intlayer الرسمية لـ VS Code**:
 
-لا تقم عادةً بتعهد هذه الموارد أو نواتج البناء الداخلية لـ `.intlayer`، لأنها يمكن أن تتولد في كل عملية بناء.
+[التثبيت من سوق VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)