التوثيق / المطوّرون
يتيح SwiftLing Pro للأنظمة الأخرى قراءة الترجمات وكتابتها، سواء كانت وكالة ترجمة تستوردها، أو محررًا بلا واجهة، أو برنامجًا نصيًا، أو تطبيقًا. ويستجيب SwiftLing نفسه لمسارات WordPress بلغة محددة ويعرض اللغات المتاحة؛ راجع docs/rest-api.md الخاص بـSwiftLing. أما ما يلي فهو ما يضيفه SwiftLing Pro.
يُقدَّم كل طلب باسم مستخدم، باستخدام مصادقة WordPress (كلمة مرور تطبيق، أو ملف تعريف الارتباط ورمز nonce لمستخدم سجّل دخوله)، ويُسمح له بما يُسمح لذلك المستخدم بفعله في محرر الترجمة: يترجم المدير أو المحرر ما يستطيع تحريره؛ ويترجم المترجم (الإعدادات › المترجمون) كل شيء، لكنه لا يستطيع تغيير المنشورات نفسها، لذا يستخدم مسارات swiftling-pro/v1. تعمل هذه المسارات مع المحتوى الأصلي، حتى عند الوصول إليه من عنوان إحدى اللغات.
نصوص المنشور أو المصطلح الخاصة به: swiftling_translations
تحتوي منشورات الأنواع التي يترجمها SwiftLing ومصطلحات القوائم التي يترجمها على الحقل swiftling_translations، سواء في مسارات WordPress (wp/v2/posts، wp/v2/pages، wp/v2/categories…) أو مسارات WooCommerce (wc/v3/products، فالمنتجات منشورات). وتُنظَّم بحسب الاسم اللطيف لكل لغة:
"swiftling_translations": {
"de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt" }
}للمصطلح name وdescription وslug. تعني السلسلة الفارغة عدم وجود ترجمة؛ وإذا كان الاسم اللطيف فارغًا، يظهر الاسم اللطيف للأصل. ويُقرأ النص الذي تغيّر أصله بعد ترجمته على أنه فارغ إلى أن يُترجم من جديد. لا يرى الزائر إلا اللغات الظاهرة للزوار، بينما يرى من يترجم جميع اللغات.
عند كتابة الترجمات مع المنشور أو المصطلح، تُحفَظ مثل أي حقل آخر:
POST /wp-json/wp/v2/posts/12
{ "swiftling_translations": {
"de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt",
"texts": { "8f14e45fceea167a5a36dedd4bea2543": "Rufen Sie uns an" },
"state": "machine" } } }- يُحفَظ
titleوexcerpt(أوnameوdescriptionللمصطلح) باسميهما؛ أماtextsفهي نصوص المنشور الأخرى، مرتبة بحسب المفتاح كما يعرضهاGET swiftling-pro/v1/texts. - تكون قيمة
stateإماreviewed(الافتراضية) أوmachine، للترجمة الآلية التي لم يراجعها شخص بعد. - يزيل النص الفارغ الترجمة؛ ويعيد الاسم اللطيف الفارغ الاسم اللطيف للأصل.
- تمنح أول ترجمة للعنوان المنشور اسمًا لطيفًا باللغة المعنية، ما لم يُحدَّد
slug.
يُتحقَّق من كل شيء قبل حفظ أي شيء، لذا تُحفَظ عملية الكتابة كاملة أو لا يُحفَظ منها شيء:
| Error | When |
|---|---|
swiftling_unknown_texts (400) | A key is no text of the post, or of a version of its original from before the post’s page was last checked. data.keys lists them; list the texts again. |
swiftling_no_original (400) | A text the post does not have, as the excerpt of a post without one. |
swiftling_placeholders (400) | A translation of a text from code asks for a value its original does not give, as %2$s, or holds a % that is no placeholder: the page would stop. data.keys lists them. |
swiftling_slug_subject (400) | A slug for what has no address of its own. |
rest_invalid_param (400) | A language the site is not translated into, or a state of none. |
عبر مسارات WooCommerce، لا يحتوي الخطأ على data.keys، لأن WooCommerce يعرضه بصيغته الخاصة.
يُفحَص المنشور الذي لم يُفحَص من قبل على الخادم أولًا، ويستغرق ذلك ثانية أو ثانيتين.
أي موضوع: swiftling-pro/v1
الموضوع هو ما يفتحه محرر الترجمة: منشور (post:12)، أو قالب لسمة تعتمد على المكوّنات (template:twentytwentyfive//archive)، أو نوع صفحة لسمة تقليدية (view:search)، أو مصطلحات قائمة (terms:category)، أو قائمة تقليدية (menu:3)، أو موضوع تابع لأداة بناء، مثل صفحة خيارات Advanced Custom Fields.
GET /wp-json/swiftling-pro/v1/texts?subject=post:12&lang=de
نصوص الموضوع وترجماتها إلى اللغة المحددة، كما يعرضها المحرر. لا تُخزَّن النصوص الأصلية، لذا تُفحَص صفحة الموضوع على الخادم أولًا.
{
"subject": { "key": "post:12", "kind": "post", "title": "Kontakt", "url": "https://example.com/kontakt/" },
"texts": [
{ "key": "1f0e3dad99908345f7439f8ffabdffc4", "object": "post:12", "path": "field/post_title",
"section": "page", "kind": "heading", "type": "text", "original": "Kontakt",
"translation": "", "state": "missing", "previous": "", "follows": false }
]
}- تكون قيمة
typeإماtextأوhtmlأوcodeأوurl(عنوان رابط أو صورة) أوformat، وهو نص من الشيفرة يحتفظ بالعناصر النائبة الموجودة في أصله. - تكون قيمة
stateإماreviewedأوmachineأوofficial(ترجمة WordPress أو السمة نفسها) أوoutdated، معpreviousالذي يحتوي على ترجمة النص الأصلي قبل تغيّره، أوmissing. - يشير
followsإلى تسمية في قائمة تعرض العنوان المترجم لصفحتها ما دامت لا تملك ترجمة خاصة بها. - يحدّد المفتاح النص ونسخة أصله: تُرفض ترجمة نسخة أقدم بعد فحص الصفحة منذ ذلك الحين.
POST /wp-json/swiftling-pro/v1/texts
{ "subject": "post:12", "lang": "de", "state": "reviewed",
"texts": { "1f0e3dad99908345f7439f8ffabdffc4": "Kontakt" } }يحفظ الترجمات بحسب المفتاح، ويتحقق منها كما يتحقق من الحقول. ويعيد states لما حُفظ، وحالة العنصر في كل لغة (languages)، وaddress المنشور في تلك اللغة.
POST /wp-json/swiftling-pro/v1/translate
{ "subject": "post:12", "lang": "de" }يملأ نصوص العنصر الفارغة باستخدام خدمة الترجمة ويحفظها كترجمات آلية، كما يفعل خيار «ترجمة كل شيء» مع الصفحة. وعند استخدام "again": ["machine"] (أو reviewed)، يعيد بدلًا من ذلك ترجمة النصوص الموجودة في تلك الحالات. ويعيد عدد texts، وعدد ما تمت translated منه، وعدد characters، وerror الخدمة إن توقفت قبل الإكمال؛ فما تُرجم قبل ذلك يبقى محفوظًا. ويمكن للمترجم استخدامه ما لم يُمنع ذلك في الإعدادات › المترجمون.
GET /wp-json/swiftling-pro/v1/to-translate?lang=de
ما لا يزال بحاجة إلى ترجمة في لغة معيّنة: افتراضيًا، ما لم يُترجم، أو تُرجم جزئيًا، أو أصبحت ترجمته قديمة، أو لم يُترجم إلا آليًا. تُقسَّم النتائج إلى صفحات كما في مسارات ووردبريس (page، وper_page بحد أقصى 100، وX-WP-Total، وX-WP-TotalPages).
| Parameter | |
|---|---|
kind | post (the default: the pages and posts visitors open), template (templates or kinds of pages, and builders’ subjects), terms, menu. |
type | For posts: one post type, as page. |
state | The states to list: missing, partial, outdated, machine, reviewed, duplicate (the language keeps the original, Keep the original in the editor). |
[ { "key": "post:12", "kind": "post", "title": "Kontakt", "state": "missing",
"url": "https://example.com/de/kontakt/", "id": 12, "type": "page" } ]العنصر الذي لم يُفحص قط لا تكون نصوصه معروفة بعد، لذا تكون حالته missing.
المتجر: swiftling_prices وswiftling_language
تتضمن مسارات WooCommerce (wc/v3) حقلين إضافيين.
للمنتجات وأشكالها حقل swiftling_prices: السعر العادي وسعر التخفيض الخاصان بالمنتج بكل عملة أخرى في المتجر (الإعدادات › العملات)، بحسب رمز العملة. وإذا كان السعر فارغًا، فلا يكون للمنتج سعر خاص بتلك العملة، ويُحوَّل السعر من عملة المتجر.
"swiftling_prices": {
"USD": { "regular": "12.50", "sale": "" },
"GBP": { "regular": "", "sale": "" }
}للطلبات حقل swiftling_language: اللغة التي قُدّم بها الطلب، والتي تُكتب بها رسائله الإلكترونية إلى العميل، أو null إذا أُنشئ الطلب من لوحة الإدارة.
"swiftling_language": { "locale": "de_DE", "slug": "de" }يُكتب كلا الحقلين مع المنتج أو الطلب، مثل حقول WooCommerce الأصلية: تُكتب الأسعار أعدادًا عشرية في سلاسل نصية وفق طريقة WooCommerce، ولا تُكتب إلا أنواع الأسعار والعملات المُقدَّمة؛ وتُحدَّد اللغة بمعرّفها المختصر أو رمزها المحلي ("de")، ويجب أن تكون إحدى لغات الموقع، بما فيها اللغة الأصلية. وتُكتب هذه القيم قبل أن يحفظ WooCommerce البيانات، لذا يُحفظ الطلب المُنشأ عبر واجهة API بلغته، وتُرسل رسائله الإلكترونية الأولى بها. وإذا كانت العملة غير متاحة في المتجر (swiftling_currency)، أو لم يكن السعر رقمًا (swiftling_price)، أو لم تكن اللغة من لغات الموقع (swiftling_language)، يُوقَف الطلب بخطأ 400 قبل حفظ أي جزء منه.
الإمكانات
Where WordPress has the Abilities API (6.9 and later), SwiftLing Pro registers its translation abilities in the category swiftling-translation, for AI agents (through an MCP adapter) and other tools. They are the same steps as the routes above, with the same rights, and run over the Abilities API’s own routes too: GET /wp-json/wp-abilities/v1/abilities/swiftling-pro/get-texts/run?input[subject]=post:12&input[lang]=de.
| Ability | |
|---|---|
swiftling-pro/list-languages | The languages, the original first. Read only. |
swiftling-pro/translation-status | The service, its characters this month, and the pages in each state per language. Read only. |
swiftling-pro/get-texts | subject, lang: as GET swiftling-pro/v1/texts. Read only. |
swiftling-pro/to-translate | lang, kind, type, state, page, per_page: as GET swiftling-pro/v1/to-translate, answering items and total. Read only. |
swiftling-pro/save-translations | subject, lang, texts (key => text), state: as POST swiftling-pro/v1/texts. |
swiftling-pro/machine-translate | subject, lang, again: as POST swiftling-pro/v1/translate. It costs characters with the service. |