ترجمة مواصفة

هذا الدليل موجّه إلى أدوار الإنتاج: عضو في فريق خلفية ينشر من المتصفح، أو خط أنابيب يستخدم سطر أوامر API-dex. في النهاية، يقرأ المستهلك الذي يبدّل البوابة إلى لغة أخرى عناوين واجهتك وملخصاتها وأوصافها بتلك اللغة، وتبقى المواصفة التي نشرتها دون تغيير بايتًا ببايت.

كيف تعمل المواصفات المترجمة

تعيش الترجمات خارج المواصفة. تنشر مواصفة أصلية واحدة كالمعتاد، إضافة إلى ملف طبقة واحد لكل لغة يحمل النص المترجم فقط. الطبقة مستند OpenAPI Overlay 1.x معياري: قائمة إجراءات، يشير كلٌّ منها إلى موضع في المواصفة بهدف JSONPath ويوفّر النص المطلوب تحديثه.

تخزّن API-dex الطبقات بجانب المواصفة وتدمج الطبقة المطابقة حين يفتح مستهلك المواصفة. لا تُعدَّل المواصفة المخزَّنة أبدًا.

• اللغات المدعومة: en-GB، nl-NL، de-DE، fr-FR، es-ES، se-SE، ar-SA.
• ترجم النص الوصفي فقط: عناوين وملخصات وأوصاف الواجهة ووسومها وعملياتها ومعاملاتها واستجاباتها وخصائص مخططاتها. اترك المسارات ومعرّفات العمليات وأسماء المعاملات وبنية المخططات كما هي، لتطابق الواجهة الموثّقة دائمًا الواجهة التي نشرتها.
• الترجمات الجزئية مقبولة. يحتفظ كل ما لا تترجمه الطبقة بنصه الأصلي. لا يظهر شيء فارغًا.

اكتب طبقة

ملف واحد لكل لغة. يترجم المثال أدناه واجهة صغيرة لمتجر حيوانات إلى الهولندية.

overlay: 1.0.0
info:
  title: Dutch translation
  version: 1.0.0
actions:
  - target: $.info
    update:
      title: Huisdierenwinkel API
      description: Nederlandse beschrijving.
  - target: $.tags[0]
    update:
      description: Huisdier bewerkingen
  - target: $.paths['/pets'].get
    update:
      summary: Huisdieren weergeven
      description: Geeft alle huisdieren terug.
  - target: $.paths['/pets'].get.parameters[0]
    update:
      description: Hoeveel items te retourneren.
  - target: $.paths['/pets'].get.responses['200']
    update:
      description: Een lijst met huisdieren.
  - target: $.components.schemas.Pet.properties.name
    update:
      description: De naam van het huisdier.

تتحقق API-dex من كل طبقة عند التحميل: يجب أن تكون كائنًا بإصدار overlay يساوي 1.x، وبإجراء واحد على الأقل، وبهدف JSONPath target إضافة إلى update أو remove في كل إجراء. يُقبل JSON وYAML معًا.

انشر من المتصفح

1

افتح Upload spec

اختر البيئة، وافتح APIs، وابدأ تحميلًا. لصفحة Upload spec أربع خطوات: Destination وSpecification وOverlays وReview.

2

اختر الوجهة والمواصفة

اختر المنتج، أو الفئة التي تتشارك منتجاتها المواصفة، ثم أسقط ملف OpenAPI.

3

أرفق الطبقات

في خطوة Overlays، اختر Attach overlay لكل لغة لديك ملف لها. الخطوة اختيارية: من دون طبقات، تعرض كل لغات البوابة المواصفة نفسها. وتنطبق الطبقات المرفقة بمواصفة فئة على كل منتج في تلك الفئة.

لجعل الترجمات إلزامية لهذا التحميل، فعّل Require an overlay for every portal language.

4

راجع وانشر

تعرض خطوة Review الوجهة والملف والطبقات المرفقة. اختر Publish.

WARNING

لا يرث إصدار المواصفة الجديد طبقات الإصدار السابق. حين تكون للمواصفة ترجمات أصلًا، تعرضها خطوة Overlays وتطلب منك الاحتفاظ بكل لغة أو استبدالها. يُمنع التحميل ما دامت لغة منشورة ستُسقَط.

انشر من خط أنابيب

أعلن الطبقات في بيان سطر أوامر API-dex، بجانب المواصفة التي تترجمها:

products:
  - name: pets-api
    openapi: openapi.yaml
    overlays:
      - locale: nl-NL
        path: overlays/nl-NL.yaml
      - locale: de-DE
        path: overlays/de-DE.yaml
categories:
  - name: payments
    openapi: payments.yaml
    overlays:            # تنطبق على كل منتج يرث هذه المواصفة
      - locale: nl-NL
        path: overlays/payments-nl-NL.yaml
    products:
      - name: refunds-api
        inheritSpec: true

ثم شغّل التحميل المعتاد:

apidex-cli upload-spec --environment <environment-id> manifest.yaml

يرفض سطر الأوامر تحميلًا يُسقط بصمت ترجمة تملكها البوابة أصلًا لتلك المواصفة. أعلن الطبقة في البيان، أو أزل الترجمات أولًا (انظر أدناه).

للتحقق من الطبقات قبل التحميل، مثلًا في CI مستودع المواصفة:

apidex-cli validate manifest.yaml --require-locales nl-NL,de-DE

يتحقق هذا من كل ملف طبقة ويفشل حين تفتقر مواصفة إلى طبقة لإحدى اللغات المطلوبة.

أزل الترجمات

يزيل المسؤولون وحسابات CI/CD كل ترجمات مواصفة عبر واجهة المنصّة:

DELETE /api/specs/{specId}/overlays

تُقدَّم المواصفة بلغتها الأصلية لكل لغات البوابة من القراءة التالية. لاستبدال لغة واحدة بدلًا من ذلك، حمّل طبقة جديدة لتلك اللغة؛ وتُترك اللغات الأخرى كما هي.

ما يراه المستهلكون

• تُعرض المواصفة بلغة البوابة التي اختارها المستهلك. حيث لا توجد طبقة لتلك اللغة، تعود API-dex إلى اللغة نفسها في منطقة أخرى (nl تقدّم nl-NL)، ثم إلى النص الأصلي.
• تبديل لغة البوابة يعيد تحميل المواصفة في مكانها.
• تنزيل المواصفة يمنح اللغة المعروضة على الشاشة. ولأن النص الوصفي فقط هو المترجم، يصف الملف الواجهة نفسها ويعمل في أي أداة OpenAPI.

مواضيع ذات صلة

• عرض واجهة برمجة التطبيقات الخاصة بك
• المرجع: كتالوج الواجهات، بما في ذلك نقاط نهاية طبقات الترجمة
• إدارة الإعدادات، حيث يختار المسؤولون لغات البوابة