@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/docs/ar/testing.md

@@ -0,0 +1,199 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: اختبار المحتوى الخاص بك
+description: اكتشف كيفية اختبار المحتوى الخاص بك باستخدام Intlayer.
+keywords:
+  - اختبار
+  - Intlayer
+  - التدويل
+  - نظام إدارة المحتوى
+  - محرر بصري
+slugs:
+  - doc
+  - testing
+---
+
+# اختبار المحتوى الخاص بك
+
+يوضح هذا الدليل كيفية التحقق تلقائيًا من اكتمال قواميسك، واكتشاف الترجمات المفقودة قبل النشر، واختبار واجهة المستخدم المحلية في تطبيقك.
+
+---
+
+## ما يمكنك اختباره
+
+- **الترجمات المفقودة**: فشل في CI إذا كانت هناك أي لغات مطلوبة مفقودة لأي قاموس.
+- **عرض واجهة المستخدم المحلية**: عرض المكونات باستخدام مزود لغة محدد والتحقق من النصوص/السمات المرئية.
+- **تدقيق وقت البناء**: إجراء تدقيق سريع محليًا عبر CLI.
+
+---
+
+## بداية سريعة: التدقيق عبر CLI
+
+شغّل التدقيق من جذر مشروعك:
+
+```bash
+npx intlayer content test
+```
+
+علامات مفيدة:
+
+- `--env-file [path]`: تحميل متغيرات البيئة من ملف.
+- `-e, --env [name]`: اختيار ملف تعريف البيئة.
+- `--base-dir [path]`: تعيين الدليل الأساسي للتطبيق لحل المسارات.
+- `--verbose`: عرض سجلات مفصلة.
+- `--prefix [label]`: إضافة بادئة لأسطر السجل.
+
+ملاحظة: يقوم CLI بطباعة تقرير مفصل لكنه لا يخرج برمز خطأ عند الفشل. لاستخدامه في CI، أضف اختبار وحدة (أسفله) يؤكد عدم وجود لغات مطلوبة مفقودة.
+
+---
+
+## اختبار برمجي (Vitest/Jest)
+
+استخدم واجهة برمجة تطبيقات Intlayer CLI للتأكد من عدم وجود ترجمات مفقودة للغات المطلوبة.
+
+```ts file=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("الترجمات", () => {
+  it("لا توجد لغات مطلوبة مفقودة", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // مفيد عند فشل الاختبار محليًا أو في CI
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+المكافئ في Jest:
+
+```ts file=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("لا توجد لغات مطلوبة مفقودة", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+كيف يعمل:
+
+- يقرأ Intlayer تكوينك (اللغات locales، اللغات المطلوبة requiredLocales) والقواميس المعلنة، ثم يبلغ عن:
+  - `missingTranslations`: لكل مفتاح، أي اللغات مفقودة ومن أي ملف.
+  - `missingLocales`: اتحاد جميع اللغات المفقودة.
+  - `missingRequiredLocales`: مجموعة فرعية محدودة بـ `requiredLocales` (أو جميع اللغات إذا لم يتم تعيين `requiredLocales`).
+
+---
+
+## اختبار واجهة المستخدم المحلية (React / Next.js)
+
+قم بعرض المكونات تحت مزود Intlayer وتحقق من المحتوى المرئي.
+
+مثال React (Testing Library):
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("renders localized title in English", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByText("العنوان الإنجليزي المتوقع")).toBeInTheDocument();
+});
+```
+
+مثال Next.js (App Router): استخدم غلاف الإطار:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("يعرض العنوان المحلي بالفرنسية", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "العنوان المتوقع" })
+  ).toBeInTheDocument();
+});
+```
+
+نصائح:
+
+- عندما تحتاج إلى قيم نصية خام للسمات (مثل `aria-label`)، قم بالوصول إلى الحقل `.value` الذي يتم إرجاعه بواسطة `useIntlayer` في React.
+- احتفظ بالقواميس بجانب المكونات لتسهيل اختبار الوحدة والتنظيف.
+
+---
+
+## التكامل المستمر
+
+أضف اختبارًا يفشل البناء عندما تكون الترجمات المطلوبة مفقودة.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+مثال على GitHub Actions:
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:i18n
+```
+
+اختياري: قم بتشغيل تدقيق CLI للحصول على ملخص قابل للقراءة البشرية إلى جانب الاختبارات:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## استكشاف الأخطاء وإصلاحها
+
+- تأكد من أن تكوين Intlayer الخاص بك يحدد `locales` و (اختياريًا) `requiredLocales`.
+- إذا كان تطبيقك يستخدم قواميس ديناميكية أو عن بُعد، فقم بتشغيل الاختبارات في بيئة تتوفر فيها القواميس.
+- بالنسبة للمستودعات المختلطة (monorepos)، استخدم `--base-dir` لتوجيه CLI إلى جذر التطبيق الصحيح.
+
+---
+
+## تاريخ الوثيقة
+
+| الإصدار | التاريخ    | التغييرات        |
+| ------- | ---------- | ---------------- |
+| 6.0.0   | 2025-09-20 | تقديم الاختبارات |

package/docs/de/autoFill.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-06-29
+updatedAt: 2025-09-20
 title: Automatisches Ausfüllen
-description: Erfahren Sie, wie Sie die Funktion zum automatischen Ausfüllen in Intlayer verwenden, um Inhalte basierend auf vordefinierten Mustern automatisch zu befüllen. Folgen Sie dieser Dokumentation, um Auto-Fill-Funktionen effizient in Ihrem Projekt zu implementieren.
+description: Erfahren Sie, wie Sie die Funktion zum automatischen Ausfüllen in Intlayer verwenden, um Inhalte basierend auf vordefinierten Mustern automatisch zu befüllen. Folgen Sie dieser Dokumentation, um Funktionen zum automatischen Ausfüllen effizient in Ihrem Projekt zu implementieren.
 keywords:
   - Automatisches Ausfüllen
   - Inhaltsautomatisierung
@@ -17,10 +17,11 @@ slugs:
   - auto-fill
 ---
 
-# Übersetzungen der Inhaltsdeklarationsdateien für automatisches Ausfüllen
+# Übersetzungen der Deklarationsdatei für automatisches Ausfüllen von Inhalten
 
-**Inhaltsdeklarationsdateien für automatisches Ausfüllen** sind eine Möglichkeit, Ihren Entwicklungsworkflow zu beschleunigen.
-Der Autofill-Mechanismus funktioniert durch eine _Master-Slave_-Beziehung zwischen Inhaltsdeklarationsdateien. Wenn die Hauptdatei (Master) aktualisiert wird, wendet Intlayer diese Änderungen automatisch auf die abgeleiteten (automatisch ausgefüllten) Deklarationsdateien an.
+**Deklarationsdateien für automatisches Ausfüllen von Inhalten** sind eine Möglichkeit, Ihren Entwicklungsworkflow zu beschleunigen.
+
+Der Mechanismus des automatischen Ausfüllens funktioniert durch eine _Master-Slave_-Beziehung zwischen Inhaltsdeklarationsdateien. Wenn die Hauptdatei (Master) aktualisiert wird, wendet Intlayer diese Änderungen automatisch auf die abgeleiteten (automatisch ausgefüllten) Deklarationsdateien an.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -30,7 +31,7 @@ const exampleContent = {
   locale: Locales.ENGLISH,
   autoFill: "./example.content.json",
   content: {
-    contentExample: "Dies ist ein Beispielinhalt",
+    contentExample: "Dies ist ein Beispielinhalt", // Beispielinhalt
   },
 } satisfies Dictionary;
 
@@ -62,11 +63,11 @@ Intlayer generiert automatisch die abgeleitete Deklarationsdatei unter `src/comp
 }
 ```
 
-Anschließend werden beide Deklarationsdateien zu einem einzigen Wörterbuch zusammengeführt, das über den standardmäßigen `useIntlayer("example")` Hook (React) / Composable (Vue) zugänglich ist.
+Anschließend werden beide Deklarationsdateien zu einem einzigen Wörterbuch zusammengeführt, das über den Standard-`useIntlayer("example")` Hook (React) / Composable (Vue) zugänglich ist.
 
-## Format der automatisch ausgefüllten Datei
+## Automatisch ausgefülltes Dateiformat
 
-Das empfohlene Format für automatisch ausgefüllte Deklarationsdateien ist **JSON**, da dies Formatierungsbeschränkungen vermeidet. Intlayer unterstützt jedoch auch `.ts`, `.js`, `.mjs`, `.cjs` und andere Formate.
+Das empfohlene Format für automatisch ausgefüllte Deklarationsdateien ist **JSON**, da es Formatierungsbeschränkungen vermeidet. Intlayer unterstützt jedoch auch `.ts`, `.js`, `.mjs`, `.cjs` und andere Formate.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -86,8 +87,8 @@ src/components/example/example.filled.content.ts
 
 > Die Generierung von `.js`, `.ts` und ähnlichen Dateien funktioniert wie folgt:
 >
-> - Wenn die Datei bereits existiert, analysiert Intlayer sie mit dem AST (Abstract Syntax Tree), um jedes Feld zu finden und fehlende Übersetzungen einzufügen.
-> - Wenn die Datei nicht existiert, wird Intlayer sie mit der Standardvorlage für die Inhaltsdeklarationsdatei generieren.
+> - Wenn die Datei bereits existiert, analysiert Intlayer sie mithilfe des AST (Abstract Syntax Tree), um jedes Feld zu finden und fehlende Übersetzungen einzufügen.
+> - Wenn die Datei nicht existiert, generiert Intlayer sie mit der Standardvorlage für Inhaltsdeklarationsdateien.
 
 ## Absolute Pfade
 
@@ -109,9 +110,9 @@ Dies erzeugt die Datei unter:
 /messages/example.content.json
 ```
 
-## Automatische Generierung von pro-Locale Inhaltsdeklarationsdateien
+## Automatische Generierung von Inhaltsdeklarationsdateien pro Locale
 
-Das Feld `autoFill` unterstützt auch die Generierung von **pro-Locale** Inhaltsdeklarationsdateien.
+Das Feld `autoFill` unterstützt auch die Generierung von **pro Locale** Inhaltsdeklarationsdateien.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -131,9 +132,11 @@ Dies erzeugt zwei separate Dateien:
 - `src/components/example/example.fr.content.json`
 - `src/components/example/example.es.content.json`
 
-## Autofill für bestimmte Locale filtern
+> In diesem Fall, wenn das Objekt nicht alle Sprachen enthält, überspringt Intlayer die Generierung der verbleibenden Sprachen.
+
+## Filter für bestimmte Sprach-Autofill
 
-Die Verwendung eines Objekts für das Feld `autoFill` ermöglicht es Ihnen, Filter anzuwenden und nur bestimmte Locale-Dateien zu generieren.
+Die Verwendung eines Objekts für das Feld `autoFill` ermöglicht es Ihnen, Filter anzuwenden und nur bestimmte Sprachdateien zu generieren.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
@@ -147,7 +150,7 @@ const exampleContent = {
 };
 ```
 
-Dies erzeugt nur die französische Übersetzungsdatei.
+Dies generiert nur die französische Übersetzungsdatei.
 
 ## Pfadvariablen
 
@@ -155,10 +158,11 @@ Sie können Variablen im `autoFill`-Pfad verwenden, um die Zielpfade für die ge
 
 **Verfügbare Variablen:**
 
-- `{{locale}}` – Gebietsschema-Code (z. B. `fr`, `es`)
+- `{{locale}}` – Sprachcode (z. B. `fr`, `es`)
+- `{{fileName}}` – Dateiname (z. B. `index`)
 - `{{key}}` – Wörterbuchschlüssel (z. B. `example`)
 
-```ts fileName="src/components/example/example.content.ts"
+```ts fileName="src/components/example/index.content.ts"
 const exampleContent = {
   key: "example",
   autoFill: "/messages/{{locale}}/{{key}}.content.json",
@@ -173,6 +177,25 @@ Dies erzeugt:
 - `/messages/fr/example.content.json`
 - `/messages/es/example.content.json`
 
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./{{fileName}}.content.json",
+  content: {
+    // Ihr Inhalt
+  },
+};
+```
+
+Dies erzeugt:
+
+- `./index.content.json`
+- `./index.content.json`
+
 ## Dokumentationsverlauf
 
-- 5.5.10 - 2025-06-29: Initialer Verlauf
+| Version | Datum      | Änderungen                          |
+| ------- | ---------- | ----------------------------------- |
+| 6.0.0   | 2025-09-20 | Globale Konfiguration hinzugefügt   |
+| 6.0.0   | 2025-09-17 | Variable `{{fileName}}` hinzugefügt |
+| 5.5.10  | 2025-06-29 | Historie initialisiert              |