المترجم 3.0: اللغات

  • مقالة

الحصول على مجموعة اللغات المدعومة حاليًا بواسطة عمليات أخرى للمترجم.

URL للطلب

إرسال GETالطلب إلى:

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0

معلمات الطلب

معلمات الطلب التي تم تمريرها على سلسلة الاستعلام هي:

معلمة الاستعلام الوصف
api-version المعلمة المطلوبة.
إصدار API التي طلبها العميل. يجب أن تكون القيمة '3.0'.
النطاق *معلمة اختيارية*.
قائمة بالأسماء مفصولة بفواصل تحدد مجموعة اللغات المراد عرضها. أسماء المجموعات المسموح بها هي: `الترجمة` و`التعريب` و`القاموس`. إذا لم يتم تحديد نطاق، فسيتم إرجاع جميع المجموعات، وهو ما يعادل تمرير `scope=translation,transliteration,dictionary`.

راجعنص الاستجابة.

عناوين الطلبات هي:

الرؤوس الوصف
Accept-Language *عنوان طلب اختياري*.
اللغة التي يجب استخدامها لسلاسل واجهة المستخدم. بعض الحقول في الاستجابة هي أسماء لغات أو أسماء المناطق. استخدم هذه المعلمة لتعريف اللغة التي يتم إرجاع هذه الأسماء. يتم تحديد اللغة من خلال توفير علامة لغة BCP 47 جيدة التكوين. على سبيل المثال، استخدم القيمة 'fr' لطلب الأسماء باللغة الفرنسية أو استخدم القيمة 'zh-Hant' لطلب الأسماء باللغة الصينية التقليدية.
يتم توفير الأسماء باللغة الإنجليزية عندما لا يتم تحديد لغة مستهدفة أو عندما لا تتوفر الترجمة.
X-ClientTraceId *عنوان طلب اختياري*.
معرّف GUID تم إنشاؤه بواسطة العميل لتعريف الطلب بشكل فريد.

المصادقة غير مطلوبة للحصول على موارد اللغة.

هيئة الاستجابة

يستخدم العميل scope معلمة الاستعلام لتحديد مجموعات اللغات التي يهتم بها.

  • scope=translation توفر اللغات المعتمدة لترجمة النص من لغة إلى أخرى؛

  • scope=transliteration يوفر إمكانات لتحويل النص بلغة واحدة من برنامج نصي إلى برنامج نصي آخر؛

  • scope=dictionary توفر أزواج اللغات التي Dictionary تقوم العمليات بإرجاع البيانات لها.

يمكن للعميل استرداد عدة مجموعات في وقت واحد عن طريق تحديد قائمة أسماء مفصولة بفواصل. على سبيل المثال، scope=translation,transliteration,dictionary قد ترجع اللغات المعتمدة لكافة المجموعات.

الاستجابة الناجحة هي كائن JSON بخاصية واحدة لكل مجموعة مطلوبة:

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

القيمة لكل خاصية كما يلي.

  • translationالخاصية

    قيمة translation الخاصية هي قاموس أزواج (مفتاح، قيمة). كل مفتاح هو علامة لغة BCP 47. يحدد المفتاح لغة يمكن ترجمة النص إليها أو ترجمتها منها. القيمة المرتبطة بالمفتاح هي كائن JSON بخصائص تصف اللغة:

    • name: عرض اسم اللغة في اللغة المطلوبة عبر Accept-Language العنوان.

    • nativeName: الاسم المعروض للغة في الإعدادات المحلية الأصلية لهذه اللغة.

    • dir: الاتجاه، وهو rtl للغات من اليمين إلى اليسار أو ltr للغات من اليسار إلى اليمين.

    مثال على ذلك:

    {
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

  • transliterationالخاصية

    قيمة transliteration الخاصية هي قاموس أزواج (مفتاح، قيمة). كل مفتاح هو علامة لغة BCP 47. يحدد المفتاح اللغة التي يمكن تحويل النص بها من نص برمجي إلى نص برمجي آخر. القيمة المرتبطة بالمفتاح هي كائن JSON بخصائص تصف اللغة والنصوص المدعومة:

    • name: عرض اسم اللغة في اللغة المطلوبة عبر Accept-Language العنوان.

    • nativeName: الاسم المعروض للغة في الإعدادات المحلية الأصلية لهذه اللغة.

    • scripts: قائمة البرامج النصية للتحويل منها. يحتوي كل عنصر من عناصر القائمة على scripts خصائص:

      • codeتعليمات برمجية لتعريف البرنامج النصي.

      • name: الاسم المعروض للبرنامج النصي في اللغة المطلوبة عبر Accept-Language العنوان.

      • nativeName: الاسم المعروض للغة في الإعدادات المحلية الأصلية لهذه اللغة.

      • dir: الاتجاه، وهو rtl للغات من اليمين إلى اليسار أو ltr للغات من اليسار إلى اليمين.

      • toScripts: قائمة البرامج النصية المتوفرة لتحويل النص إليها. يحتوي كل عنصر من عناصر toScriptsالقائمة على خصائصcode وname وnativeName وdir كما هو موضح سابقًا.

    مثال على ذلك:

    {
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr"
            }
          ]
        }
      ]
    },
    ...
  }
}

  • dictionaryالخاصية

    قيمة dictionary الخاصية هي قاموس أزواج (مفتاح، قيمة). كل مفتاح هو علامة لغة BCP 47. يحدد المفتاح اللغة التي تتوفر لها ترجمات بديلة وترجمات خلفية. القيمة هي كائن JSON يصف لغة المصدر واللغات الهدف مع الترجمات المتاحة:

    • name: عرض اسم اللغة في الإعدادات المطلوبة للغة المصدر عبر Accept-Language العنوان.

    • nativeName: الاسم المعروض للغة في الإعدادات المحلية الأصلية لهذه اللغة.

    • dir: الاتجاه، وهو rtl للغات من اليمين إلى اليسار أو ltr للغات من اليسار إلى اليمين.

    • translations: قائمة باللغات ذات الترجمات البديلة والأمثلة للاستعلام المعبر عنها باللغة المصدر. يحتوي كل عنصر من translations القائمة على خصائص:

      • name: عرض اسم اللغة في الإعدادات المطلوبة للغة الهدف عبر Accept-Language العنوان.

      • nativeName: الاسم المعروض للغة الهدف في الإعدادات المحلية الأصلية لهذه اللغة المستهدفة.

      • dir: الاتجاه، وهو rtl للغات من اليمين إلى اليسار أو ltr للغات من اليسار إلى اليمين.

      • code: رمز اللغة الذي يحدد اللغة الهدف.

    مثال على ذلك:

    "es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

لا تتغير بنية كائن الاستجابة دون تغيير في إصدار واجهة برمجة التطبيقات. بالنسبة لنفس الإصدار من API، قد تتغير قائمة اللغات المتاحة بمرور الوقت لأن Microsoft Translator يوسع باستمرار قائمة اللغات التي تدعمها خدماته.

لا تتغير قائمة اللغات المدعومة بشكل متكرر. لحفظ النطاق الترددي للشبكة وتحسين الاستجابة، يجب أن يأخذ تطبيق العميل في الاعتبار تخزين موارد اللغة مؤقتًا وعلامة الكيان المقابلة (ETag). بعد ذلك، يمكن لتطبيق العميل بشكل دوري (على سبيل المثال، مرة كل 24 ساعة) الاستعلام عن الخدمة لجلب أحدث مجموعة من اللغات المدعومة. يسمح تمرير القيمة الحالية ETag في If-None-Match حقل رأس للخدمة بتحسين الاستجابة. إذا لم يتم تعديل المورد، ترجع الخدمة رمز الحالة 304 ونص استجابة فارغ.

رؤوس الاستجابة

الرؤوس الوصف
ETag القيمة الحالية لعلامة الكيان لمجموعات اللغات المدعومة المطلوبة. لجعل الطلبات اللاحقة أكثر كفاءة، قد يرسل العميل قيمة "ETag" في حقل العنوان "If-None-Match".
X-RequestId القيمة الناتجة عن الخدمة لتحديد الطلب. يُستخدم لأغراض استكشاف الأخطاء وإصلاحها.

الرموز الخاصة بحالة الاستجابة

فيما يلي تعليمات حالة HTTP البرمجية المحتملة التي يعرضها الطلب.

التعليمة البرمجية للحالة الوصف
200 نجاح
304 لم يتم تعديل المورد منذ الإصدار المحدد بواسطة عناوين الطلب "If-None-Match".
400 إحدى معلمات الاستعلام مفقودة أو غير صالحة. تصحيح معلمات الطلب قبل إعادة المحاولة.
429 رفض الخادم الطلب لأن العميل تجاوز حدود الطلب.
500 لقد حدث خطأ غير متوقع. في حالة استمر الخطأ، فقم بالإبلاغ عنه مع تاريخ/ وقت الخطأ، وأطلب معرف من عنوان الاستجابة X-RequestId، ومعرف العميل من عنوان الطلب X-ClientTraceId.
503 الخادم غير متوفر مؤقتًا. إعادة محاولة الطلب. في حالة استمر الخطأ، فقم بالإبلاغ عنه مع: تاريخ/ وقت الخطأ، وأطلب معرف من عنوان الاستجابة X-RequestId، ومعرف العميل من عنوان الطلب X-ClientTraceId.

في حال حدوث خطأ، يقوم الطلب أيضاً بإرجاع استجابة خطأ JSON. رمز الخطأ هو رقم مكون من 6 أرقام يجمع بين رمز حالة HTTP المكون من 3 أرقام متبوعاً برقم مكون من 3 أرقام لتصنيف الخطأ بشكل أكبر. يمكن العثور على رموز الخطأ الشائعة في صفحة مرجع الإصدار 3 من المترجم.

أمثلة

يوضح المثال التالي كيفية استرداد اللغات المدعومة لترجمة النص.

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"