# التدقيق اللغوي

> دقّق نصًا عاديًا لغويًا بحثًا عن الأخطاء الإملائية والنحوية وأخطاء علامات الترقيم واختيار الكلمات عبر POST /text/grammar. حقول الطلب والاستجابة، والفئات، والإزاحات، والحدود، والفوترة.

المصدر: https://fileverity.com/ar/docs/grammar

يدقّق `POST /text/grammar` نصًا واحدًا لغويًا بالنموذج `grammar-1`. يعيد كل تصحيح مقترح مع موضعه في النص وفئته وشرح موجز. وهو متزامن: النتيجة في الاستجابة نفسها.

يعمل مع العربية والإنجليزية والفرنسية والإسبانية. احفظ نصًا من 20 كلمة أو أكثر باسم `essay.txt` لتشغيل الأمثلة.

**الطلب: cURL**

```bash
curl https://api.fileverity.com/v1/text/grammar \
  -H "Authorization: Bearer $FILEVERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c7d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e21" \
  -d "$(jq -Rs '{text: ., language: "en"}' essay.txt)"
```

**الطلب: JavaScript**

```javascript
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const response = await fetch("https://api.fileverity.com/v1/text/grammar", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.FILEVERITY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({ text: await readFile("essay.txt", "utf8"), language: "en" }),
});
const check = await response.json();
```

**الطلب: Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.fileverity.com/v1/text/grammar",
    headers={
        "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"},
)
check = response.json()
```

## محتوى الطلب

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `text` | string | نعم | نص عادي لا يقل عن 20 كلمة ولا يزيد على 30,000 حرف. |
| `model` | string | لا | الافتراضي `grammar-1`. يقبل معرّف النموذج أو معرّف نسخته المؤرَّخة `grammar-1-2026-11-16`. |
| `language` | string أو null | لا | رمز ISO 639-1: `en` أو `es` أو `fr` أو `ar`. يُكتشف تلقائيًا عند عدم إرساله؛ أرسله عندما يجمع النص بين لغات. |

تُرفض الحقول غير المعروفة برمز الخطأ `invalid_parameter`. ويُعاد `unsupported_language` للنص بلغة أخرى أو الذي يتعذّر التعرف على لغته.

## الاستجابة

**200 OK**

```json
{
  "id": "tgr_8Hk2pQ4vN9sL1xR7cW3mY6zB",
  "object": "text.grammar",
  "created": 1794787200,
  "model": "grammar-1-2026-11-16",
  "livemode": true,
  "language": "en",
  "words": 412,
  "edits": [
    {
      "start": 118,
      "end": 125,
      "original": "recieve",
      "replacement": "receive",
      "category": "spelling",
      "message": "The word is spelled receive."
    },
    {
      "start": 402,
      "end": 414,
      "original": "has went",
      "replacement": "has gone",
      "category": "grammar",
      "message": "The past participle of go is gone."
    },
    {
      "start": 1170,
      "end": 1175,
      "original": "Their",
      "replacement": "They're",
      "category": "word",
      "message": "They're is the contraction of they are."
    },
    {
      "start": 1788,
      "end": 1789,
      "original": ",",
      "replacement": ";",
      "category": "punctuation",
      "message": "Two complete sentences are joined with a comma."
    }
  ],
  "counts": {
    "spelling": 1,
    "grammar": 1,
    "punctuation": 1,
    "word": 1,
    "style": 0
  },
  "version": "2026.11-g1",
  "usage": {
    "characters": 2412,
    "billed_units": 1,
    "credits": 1
  }
}
```

| الحقل | النوع | الوصف |
| --- | --- | --- |
| `id` | string | معرّف الفحص، بالبادئة `tgr_`. |
| `object` | string | دائمًا `text.grammar`. |
| `created` | integer | طابع زمني بصيغة Unix. |
| `model` | string | النسخة المؤرَّخة التي أنتجت النتيجة. |
| `livemode` | boolean | `false` لمفاتيح الاختبار. |
| `language` | string | اللغة المستخدمة: التي أرسلتها، أو التي اكتُشفت. |
| `words` | integer | عدد الكلمات في النص. |
| `edits` | array | التصحيحات المقترحة بترتيب ورودها في النص. لكل منها `start` و`end` (غير مضمَّن في النطاق) و`original` و`replacement` و`category` و`message`. لا تتداخل التعديلات أبدًا. |
| `counts` | object | عدد التعديلات في كل فئة: `spelling` و`grammar` و`punctuation` و`word` و`style`. |
| `version` | string | إصدار طريقة التدقيق. قارن النتائج داخل الإصدار الواحد فقط. |
| `usage` | object | `characters` الأحرف التي جرى تقييمها، و`billed_units` الوحدات المحتسبة، و`credits` وحدات رصيد المخصومة. |

> **ملاحظة.** تأتي الاقتراحات من نموذج لغوي. قد تكون خاطئة أو غير ضرورية، خاصةً في الأسماء والمصطلحات التقنية والأسلوب المقصود، لذا اعرضها على شخص بوصفها اقتراحات بدلًا من تطبيقها تلقائيًا. التدقيق اللغوي للعربية جديد ولا يزال قيد التقييم.

## الفئات

| `category` | المعنى |
| --- | --- |
| `spelling` | كلمة مكتوبة بخطأ إملائي. |
| `grammar` | المطابقة والزمن وأدوات التعريف وحروف الجر وترتيب الكلمات وما شابه ذلك. |
| `punctuation` | علامات الترقيم والأحرف الكبيرة والصغيرة. |
| `word` | كلمة خاطئة أو مختلطة بأخرى. |
| `style` | اقتراح لتحسين القراءة وليس خطأً. لا يُعاد منه إلا القليل، وفقط حيث تكون الجملة عسيرة القراءة بوضوح. |

## تطبيق التعديلات

`start` و`end` إزاحتان في النص الذي أرسلته، تُحسبان بنقاط رمز Unicode، وليس بالبايتات ولا بوحدات UTF-16. و`original` هو النص الواقع بينهما. لبناء النص بعد التصحيح، استبدل كل نطاق بـ `replacement` مع العمل من آخر تعديل إلى أول تعديل حتى تبقى الإزاحات السابقة صحيحة، أو قسّم النص إلى نقاط رمز أولًا:

**بناء النص بعد التصحيح: JavaScript**

```javascript
const points = Array.from(text);
const out = [];
let at = 0;
for (const edit of check.edits) {
  out.push(points.slice(at, edit.start).join(""), edit.replacement);
  at = edit.end;
}
out.push(points.slice(at).join(""));
const corrected = out.join("");
```

**بناء النص بعد التصحيح: Python**

```python
corrected = text
for edit in reversed(check["edits"]):
    corrected = corrected[: edit["start"]] + edit["replacement"] + corrected[edit["end"] :]
```

تُفهرَس سلاسل Python أصلًا بنقاط الترميز.

## الفوترة

- تبلغ تكلفة التدقيق اللغوي وحدة رصيد واحدة لكل 5,000 حرف، تُحتسب بنقاط رمز Unicode. يُقرَّب كل طلب إلى وحدات كاملة بالرفع، بحد أدنى وحدة واحدة.
- `usage.billed_units` هو عدد الوحدات المحتسبة و`usage.credits` وحدات الرصيد المخصومة. مثال: يُحتسب 2,412 حرفًا بوحدة واحدة، أي وحدة رصيد واحدة.
- لا تُحتسب رسوم على الطلبات المرفوضة قبل التقييم: المعاملات غير الصالحة، والنص القصير جدًا أو الطويل جدًا، واللغات غير المدعومة وما شابه. وإذا فشل الفحص داخل الخدمة (`service_unavailable`) فيُحرَّر المبلغ المحجوز ولا يُحتسب عليك.
- عند عدم كفاية وحدات الرصيد يُرجع الطلب `insufficient_balance` (402). عبر API يتاح التدقيق اللغوي لمساحات العمل التي اشترت وحدات رصيد، ويستهلك وحدات رصيد دائمًا؛ أما على الموقع وفي لوحة التحكم فهو ضمن خطة Pro.

## ما الذي يُخزَّن

يُرسل النص إلى نموذج لغوي عبر Vercel AI Gateway طوال مدة الفحص. وتُحفظ نسخة من النص مشفّرة مدة تصل إلى 3 سنوات لتدريب نماذج الكشف في Fileverity وتقييمها؛ راجع [الاحتفاظ بالبيانات والأمان](https://fileverity.com/ar/docs/security.md#retention). تحتفظ Fileverity بالنتيجة (التعديلات مع مقتطفاتها القصيرة الأصلية والبديلة، والأعداد، والاستخدام) مدة 7 أيام، حتى تعرضها لوحة التحكم ويمكن احتساب الاستخدام وتدقيقه. ويحصل الطلب المُعاد الذي يحمل `Idempotency-Key` نفسه على النتيجة المحفوظة خلال 24 ساعة. عمليات التدقيق اللغوي متزامنة: فلا تظهر في `GET /analyses` ولا تُرسل أحداث Webhook. ولا تسجّل مفاتيح الاختبار شيئًا. راجع [الاحتفاظ بالبيانات والأمان](https://fileverity.com/ar/docs/security.md).

## الأخطاء

| الرمز | الحالة | السبب |
| --- | --- | --- |
| `text_too_short` | 400 | أقل من 20 كلمة. |
| `text_too_long` | 413 | أكثر من 30,000 حرف. قسّم النص إلى عدة طلبات. |
| `unsupported_language` | 400 | النص ليس بالعربية أو الإنجليزية أو الفرنسية أو الإسبانية، أو تعذّر التعرف على لغته. أرسل `language` لاختيار إحداها. |
| `unsupported_media_type` | 415 | لم يُرسل محتوى الطلب بصيغة `application/json`. |
| `invalid_json`, `missing_parameter`, `invalid_parameter` | 400 | المحتوى ليس كائن JSON، أو `text` مفقود، أو نوع أحد الحقول خاطئ، أو أُرسل حقل غير معروف. |
| `model_not_found` | 404 | قيمة `model` غير معروفة. |
| `plan_required` | 403 | لم تشترِ مساحة العمل وحدات رصيد بعد. اشترِ باقة وحدات رصيد من لوحة التحكم. |
| `insufficient_balance` | 402 | الرصيد لا يغطي الطلب. |
| `spend_limit_reached` | 402 | بلغ المفتاح حد إنفاقه الشهري. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | استُخدم `Idempotency-Key` مع محتوى طلب مختلف، أو لا يزال طلبه الأول قيد التنفيذ. |
| `service_unavailable`, `analysis_failed` | 503, 502 | خدمة التدقيق اللغوي غير متاحة مؤقتًا. لا تُحتسب رسوم؛ أعد المحاولة. يحمل `service_unavailable` ترويسة `retry-after`. |

> **ملاحظة.** أرسل `Idempotency-Key` حتى لا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى احتساب الرسم مرتين. راجع [منع التكرار](https://fileverity.com/ar/docs/idempotency.md).

