REST API i AI agenti (SwiftLing Pro)

Dokumentacija / Razvojni programeri

SwiftLing Pro omogućuje drugim sustavima čitanje i zapisivanje prijevoda: uvoz iz prevoditeljske agencije, uređivač bez korisničkog sučelja, skripta ili aplikacija. Sam SwiftLing odgovara na WordPressove rute na određenom jeziku i navodi dostupne jezike; pogledajte SwiftLingov docs/rest-api.md. Evo što tome dodaje SwiftLing Pro.

Svaki se zahtjev izvršava u ime korisnika, uz WordPressovu autentifikaciju (lozinkom aplikacije ili kolačićem i nonce vrijednošću prijavljenog korisnika), i može učiniti ono što taj korisnik smije u uređivaču prijevoda: administrator ili urednik prevodi ono što smije uređivati; prevoditelj (Postavke › Prevoditelji) prevodi sve, ali ne smije mijenjati same objave, pa se služi rutama swiftling-pro/v1. Te rute rade s izvornicima, čak i na adresi pojedinog jezika.

Vlastiti tekstovi objave ili pojma: swiftling_translations

Objave vrsta koje SwiftLing prevodi i pojmovi popisa koje prevodi imaju polje swiftling_translations na WordPressovim rutama (wp/v2/posts, wp/v2/pages, wp/v2/categories…) i WooCommerceovim rutama (wc/v3/products, čiji su proizvodi objave). Prema slugu svakog jezika:

"swiftling_translations": {
  "de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt" }
}

Pojam ima name, description i slug. Prazan niz znači da prijevoda nema; ako je slug prazan, prikazuje se slug izvornika. Tekst čiji se izvornik promijenio nakon prevođenja prikazuje se kao prazan dok se ponovno ne prevede. Posjetitelj vidi samo jezike dostupne posjetiteljima, a osoba koja prevodi vidi sve jezike.

Kada se pošalje uz objavu ili pojam, kao i bilo koje drugo polje, njime se spremaju prijevodi:

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 i excerpt (name i description pojma) spremaju se po nazivu; texts su ostali tekstovi objave, određeni ključem, kako ih navodi GET swiftling-pro/v1/texts.
• state je reviewed (zadana vrijednost) ili machine, za strojni prijevod koji još treba provjeriti.
• Prazan tekst uklanja prijevod; prazan slug vraća slug izvornika.
• Prvim prijevodom naslova objava dobiva slug na tom jeziku, osim ako je zadan slug.

Sve se provjerava prije spremanja bilo čega, pa se upis sprema u cijelosti ili se uopće ne sprema:

Na WooCommerceovim rutama pogreška nema data.keys: WooCommerce je vraća kao vlastitu.

Objava koja još nije provjerena najprije se provjerava na poslužitelju, što traje sekundu ili dvije.

Bilo koja stavka: swiftling-pro/v1

Stavka je ono što se otvara u uređivaču prijevoda: objava (post:12), predložak blok-teme (template:twentytwentyfive//archive), vrsta stranice klasične teme (view:search), pojmovi popisa (terms:category), klasični izbornik (menu:3) ili stavka iz alata za izradu stranica, primjerice stranica s opcijama dodatka Advanced Custom Fields.

GET /wp-json/swiftling-pro/v1/texts?subject=post:12&lang=de

Tekstovi stavke s prijevodima na odabrani jezik, kako su navedeni u uređivaču. Izvornici se ne pohranjuju, pa se stranica stavke najprije provjerava na poslužitelju.

{
  "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 je text, html, code, url (adresa: poveznica ili slika) ili format, tekst iz koda koji zadržava rezervirana mjesta izvornika.
• state je reviewed, machine, official (vlastiti prijevod WordPressa ili teme), outdated, uz previous, prijevod izvornika prije njegove promjene, ili missing.
• follows je oznaka stavke izbornika koja prikazuje prevedeni naslov pripadajuće stranice dok nema vlastiti prijevod.
• Ključ označava tekst i verziju njegova izvornika: prijevod starije verzije odbija se nakon što se stranica ponovno provjeri.

POST /wp-json/swiftling-pro/v1/texts

{ "subject": "post:12", "lang": "de", "state": "reviewed",
  "texts": { "1f0e3dad99908345f7439f8ffabdffc4": "Kontakt" } }

Sprema prijevode po ključu, uz iste provjere kao za polja. U odgovoru vraća states spremljenih prijevoda, stanje sadržaja na svakom jeziku (languages) i address objave na tom jeziku.

POST /wp-json/swiftling-pro/v1/translate

{ "subject": "post:12", "lang": "de" }

Popunjava prazne tekstove sadržaja pomoću usluge prevođenja i sprema ih kao strojne prijevode, kao što opcija Prevedi sve čini za stranicu. Uz "again": ["machine"] (ili reviewed) umjesto toga ponovno prevodi tekstove u tim stanjima. U odgovoru navodi koliko je bilo texts, koliko ih je translated, broj njihovih characters i error usluge ako se postupak prekine: ono što je dotad prevedeno ostaje spremljeno. Prevoditelj ga može upotrebljavati osim ako je to zabranjeno u Postavke › Prevoditelji.

GET /wp-json/swiftling-pro/v1/to-translate?lang=de

Što još treba prevesti na određeni jezik: prema zadanim postavkama, ono što nije prevedeno, što je djelomično prevedeno, zastarjelo ili prevedeno samo strojno. Rezultati se dijele na stranice kao i kod WordPressovih ruta (page, per_page do 100, X-WP-Total, X-WP-TotalPages).

[ { "key": "post:12", "kind": "post", "title": "Kontakt", "state": "missing",
    "url": "https://example.com/de/kontakt/", "id": 12, "type": "page" } ]

Za sadržaj koji nikad nije provjeren tekstovi još nisu poznati, pa je njegovo stanje missing.

Trgovina: swiftling_prices i swiftling_language

WooCommerceove rute (wc/v3) sadrže još dva polja.

Proizvodi i varijacije imaju swiftling_prices: vlastitu redovnu i sniženu cijenu proizvoda u svakoj od ostalih valuta trgovine (Postavke › Valute), prema kodu valute. Ako je cijena prazna, proizvod nema vlastitu cijenu u toj valuti, pa se cijena preračunava iz valute trgovine.

"swiftling_prices": {
  "USD": { "regular": "12.50", "sale": "" },
  "GBP": { "regular": "", "sale": "" }
}

Narudžbe imaju swiftling_language: jezik na kojem je narudžba izvršena i na kojem se pišu e-poruke kupcu, ili null za narudžbu izrađenu u administraciji.

"swiftling_language": { "locale": "de_DE", "slug": "de" }

Oba se polja zapisuju zajedno s proizvodom ili narudžbom, kao vlastita polja WooCommercea: cijene kao decimalni brojevi u nizovima znakova, onako kako ih WooCommerce zapisuje, i to samo za navedene vrste cijena i valute; jezik se zadaje oznakom ili lokalnom oznakom ("de") i mora biti jedan od jezika web-mjesta, uključujući izvorni. Zapisuju se prije nego što WooCommerce spremi podatke, pa se narudžba izrađena putem API-ja sprema sa svojim jezikom, a njezine prve e-poruke šalju se na tom jeziku. Valuta koju trgovina nema (swiftling_currency), cijena koja nije broj (swiftling_price) ili jezik koji web-mjesto nema (swiftling_language) zaustavlja zahtjev s kodom 400 prije nego što se išta iz njega spremi.

Mogućnosti

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.