Lokalizuj przez API: ciągi znaków, e-maile i dokumenty – od początku do końca

Wszystko, co potrafi edytor, zrobi też skrypt: od importu, przez tłumaczenie na wiele języków z użyciem Twojego glosariusza i pamięci, po weryfikację i eksport. Ten przewodnik przeprowadzi Cię od uzyskania klucza do gotowych tłumaczeń, a następnie przez każdy etap całego cyklu. Interaktywna dokumentacja i OpenAPI JSON stanowią kompletną specyfikację; transept.ai/developers to skrócona, jednostronicowa wersja tego przewodnika. Zanim wykonasz pierwsze wywołanie, mała uwaga co do nazewnictwa: jednostką rozliczeniową wszędzie tam, gdzie tekst czyta człowiek, są słowa, ale w polach odpowiedzi API zachowano historyczną nazwę credits (estimatedCredits, spendable). To ta sama wartość.

Uzyskaj klucz

W aplikacji przejdź do sekcji Ustawienia → Deweloper i skopiuj klucz tajny (wyświetla się tylko raz). W żądaniach przesyłaj go jako Authorization: Bearer tsk_live_… – wyłącznie w nagłówku, nigdy w adresie URL.

Klucze mają określone zakresy: pełny dostęp lub odczyt/zapis w poszczególnych obszarach (dokumenty, uruchomienia, glosariusze, przewodniki stylistyczne, pamięć tłumaczeniowa, webhooki, projekty). Wywołanie spoza zakresu klucza zwraca błąd 403 z informacją o brakujących uprawnieniach. Klucz nie może generować kolejnych kluczy; zarządzanie nimi odbywa się wyłącznie w aplikacji.

Pełny obieg w pięciu wywołaniach

Zweryfikuj działanie klucza, utwórz dokument, wyceń uruchomienie, uruchom je i pobierz wynik.

export KEY="tsk_live_…"
BASE="https://app.transept.ai/api/public/v1"

# 1: who am I, what can this key do, what's the balance?
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2: a document plus its target-language fan-out, in one call
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome\n\nStart your free trial.",
       "content_type": "markdown", "source_language": "en",
       "target_language": "de", "target_languages": ["fr", "uk"]}'
# → { document_id, language_group: [ {id, target_language}, … ] }

# 3: price it (free, no side effects), then run it across every language
curl -s $BASE/workflow-templates -H "Authorization: Bearer $KEY"   # discover ids

curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { lanes: [ {language, estimatedCredits, minCredits} ], totals: {sufficient} }

curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-2026-08-05" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { id: <group_run_id>, runs: [ {job_id, language, block_count} ] }

# 4: wait by polling, or get pushed a signed event instead
curl -s $BASE/group-runs/<group_run_id> -H "Authorization: Bearer $KEY"
# → { status, runs: [ {language, status, progress, gate} ] }

# 5: read the results in the format your pipeline wants
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Trzy nawyki od pierwszego dnia: najpierw wyceniaj (bezpłatnie; otrzymasz zakres od dolnej do górnej granicy, a ta górna jest korygowana do faktycznego zużycia), **wysyłaj ** **Idempotency-Key** ** przy żądaniach POST tworzących zadania (ponowienie żądania zwróci wynik pierwszej próby zamiast naliczać opłatę dwukrotnie) oraz zarejestruj webhook ( POST /webhooks {url, events: ["group_run.completed"]} ) zamiast stosować odpytywanie. Powiadomienia są podpisywane skrótem HMAC, obsługują ponowienia i mają swój dziennik doręczeń.

Trzy rodzaje danych wejściowych

Tekst ciągły i e-maile

POST /documents z content_type: "html" zachowuje formatowanie, linki i symbole zastępcze szablonu podczas tłumaczenia; format=html zwraca przetłumaczony e-mail w tym samym układzie. Możesz też pominąć samo żądanie: ustaw wyzwalacz workflow na „treść żądania jest zawartością” i skieruj swój system ESP, Zapier/n8n lub CI na adres URL wyzwalacza:

# the trigger URL (with its secret) comes from the workflow's trigger card;
# the secret IS the auth, so no Authorization header
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: application/json" \
  -d '{"content": "<h1>Welcome!</h1><p>Your trial starts today.</p>",
       "content_type": "html",
       "title": "Trial welcome",
       "external_id": "welcome-v4"}'
# → 202 { run id, document_id, created }

# raw bodies work too: POST the markdown/HTML itself with its Content-Type
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: text/markdown" \
  --data-binary $'# Welcome\n\nStart your free trial.'

Wyzwalacz decyduje, czy każde przesłanie danych tworzy nowy dokument, czy aktualizuje jeden stały dokument (aktualizacja dopasowuje treść, dzięki czemu tłumaczone są tylko zmienione bloki). Przez 24 godziny powtarzające się zgłoszenia są deduplikowane na podstawie external_id lub skrótu treści (hash). Zobacz wyzwalacze webhook.

Pliki

POST /documents/upload (multipart) przyjmuje plik wraz z polami source_language, target_language oraz opcjonalnymi target_languages[] i project_id. Pliki DOCX obsługują pełny cykl (round-trip): eksport nanosi tłumaczenia bezpośrednio na oryginalny plik, dzięki czemu style i układ zostają zachowane. Z kolei formaty CSV, PO i XLIFF są importowane jako wpisy z kluczami i eksportowane z powrotem w swoich pierwotnych formatach. Szczegóły dotyczące formatów i mapowania kolumn: pliki z ciągami znaków.

Katalogi tekstowe

Każdy ciąg znaków stanowi jednostkę o stałym id, zawierającą pole source oraz opcjonalne context, max_length i placeholders:

curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

Kontekst trafia do modelu jako wskazówka dla tłumacza, limit max_length jest wymuszany poprzez skracanie tekstu i ponawianie prób, symbole zastępcze są chronione, a formy liczby mnogiej są rozwijane zgodnie z zasadami danego języka. Tłumaczenia już obecne w pliku są bezpłatnie ustawiane jako aktywne i zasilają pamięć tłumaczeniową. Brak języków docelowych skutkuje błędem no_target_languages, co zapobiega importowaniu dokumentu, który nie zostałby przetłumaczony na żaden język. Pełny proces opisano w artykule Lokalizacja katalogu tekstowego przez API.

Jeden szablon e-maila, trzy języki

Przykład e-maila w praktyce. Tagi Liquid pozostają nienaruszone podczas tłumaczenia:

# the template body goes in as HTML; three target languages fan out
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Trial welcome", "content_type": "html", "source_language": "en",
       "target_languages": ["de", "fr", "uk"],
       "content": "<h1>Welcome, {{ first_name | default:\"friend\" }}!</h1><p>Your trial starts today.</p>"}'

{{ first_name | … }} jest maskowane przed przekazaniem tekstu do modelu i przywracane w niezmienionej formie. Wyjątek stanowi wartość domyślna friend – jako treść widoczna dla odbiorcy PODLEGA ona tłumaczeniu, podczas gdy sam tag pozostaje nienaruszony. Uruchom grupę zadań zgodnie z instrukcją szybkiego startu, a następnie odczytaj wyniki dla poszczególnych języków:

curl -s "$BASE/documents/<de-version-id>/content?format=html" \
  -H "Authorization: Bearer $KEY"
# → the same HTML with German copy, Liquid intact; paste it into the ESP's de variant

Wariant bezobsługowy: wyzwalacz typu payload webhook pobiera szablon bezpośrednio z systemu ESP, workflow uruchamia się natychmiast po odebraniu danych, a webhook group_run.completed odsyła przetłumaczony kod HTML. Szczegóły dotyczące konkretnych platform (tagi Braze, instrukcje warunkowe Mailchimp): szablony e-mail ESP oraz przewodnik po lokalizacji e-maili.

Słowniki, poradniki stylu, pamięć tłumaczeniowa

Utwórz słownik, dodając do niego terminy w tym samym żądaniu:

curl -s -X POST $BASE/glossaries \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product terms", "source_language": "en",
       "terms": [{"source_term": "Transept", "target_term": "Transept",
                  "do_not_translate": true}]}'

Rozbuduj istniejący słownik (lista dostępnych dla Twojego klucza znajduje się pod GET /glossaries):

curl -s -X POST $BASE/glossaries/<id>/terms/bulk \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"terms": [
        {"source_term": "workspace", "target_term": "Arbeitsbereich"},
        {"source_term": "run", "target_term": "Lauf", "notes": "the noun: a workflow execution"}
      ]}'

Możesz je również wygenerować na podstawie zaufanego dokumentu: służą do tego POST /glossaries/{id}/auto-build oraz POST /styleguides/generate (oba mają bezpłatne warianty …/estimate). Obie operacje są płatne od słowa i wymagają ustawienia auto_apply: true w API. W trybie headless pomijany jest etap weryfikacji, więc wynik zostaje zatwierdzony automatycznie po zakończeniu zadania. Stan operacji sprawdzisz przez GET /generation-jobs/{id}. Alternatywą z możliwością przejrzenia zmian w aplikacji jest tworzenie na podstawie dokumentu. Wystarczy podpiąć je raz – każde kolejne uruchomienie przez API, MCP czy edytor będzie z nich korzystać bez dodatkowych opłat:

curl -s -X PATCH $BASE/documents/<id>/translation-settings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"glossary_ids": ["<glossary_id>"], "styleguide_version_ids": ["<active_version_id>"]}'

Poradniki stylu przypisuje się za pomocą identyfikatora aktywnej wersji (z GET /styleguides/{id}); wartość [] odłącza je. Obie opcje działają również przy tworzeniu dokumentu przez POST /documents. W interfejsie: słowniki, poradniki stylu. Pamięć tłumaczeniowa nie wymaga ręcznego przypisywania: każde ukończone tłumaczenie jest indeksowane i automatycznie wykorzystywane ponownie. Możesz wysyłać do niej zapytania (POST /translation-m``emory/query, bezpłatnie), zasilać ją plikami TMX/XLIFF (POST /translation-memory/import, bezpłatnie) lub wyeksportować całą jej zawartość (GET /translation-memory/export-tmx). Zobacz: pamięć tłumaczeniowa oraz importowanie istniejących tłumaczeń.

Zespoły

Klucz zespołowy korzysta z puli zespołu i dziedziczy jego projekty, słowniki, poradniki stylu oraz pamięć tłumaczeniową. Dokumenty w ramach zespołu utworzysz, podając project_id projektu zespołowego (listę projektów zwraca GET /projects; projekty zespołowe zawierają pole team_id). Cała reszta działa identycznie jak w przypadku kont osobistych. Zespoły i projekty skonfigurujesz w aplikacji: projekty, zespoły i zaproszenia.

Uruchomienia i bramki weryfikacyjne

POST /runs obsługuje pojedynczą wersję językową; POST /group-runs rozsyła zadania na wszystkie języki docelowe, tworząc w razie potrzeby brakujące wersje. Oba endpointy oferują darmową wycenę, obsługują nagłówek Idempotency-Key i pozwalają na anulowanie operacji. Krok przepływu pracy ustawiony na oczekiwanie na weryfikację wstrzymuje bieg procesu: GET /runs/{id} zwraca wtedy gate_pending: true wraz z podsumowaniem wyników weryfikacji. Od strony użytkownika za obsługę tej przerwy odpowiadają panel recenzenta oraz weryfikacja z asystą; od strony skryptu:

# continue downstream steps (all blocks, or a reviewed subset):
curl -s -X POST $BASE/runs/<id>/gate/approve \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"approved_block_ids": ["…"]}'    # omit the field to approve all

# a gate with nothing downstream is dismissed instead:
curl -s -X POST $BASE/runs/<id>/gate/acknowledge -H "Authorization: Bearer $KEY"

Zatrzymany proces nigdy nie rusza samoczynnie – wymaga wyraźnego zatwierdzenia przez skrypt, asystenta MCP lub użytkownika w aplikacji. Nie istnieje żadna flaga startowa, która pozwalałaby automatycznie pomijać etapy weryfikacji. Jeśli proces ma przebiegać bez żadnych przerw, należy skorzystać z przepływu pracy pozbawionego kroku kontrolnego.

Formaty wyjściowe

GET /documents/{id}/content?format=<f> dla identyfikatora wersji językowej:

format=strings wywołany na dokumencie głównym zwraca wszystkie języki w jednej odpowiedzi, gotowe do zatwierdzenia.

Aktualizacja wyłącznie różnic

W przypadku katalogów tekstowych prześlij ponownie cały aktualny plik; serwer sam wyliczy różnice:

# 1: re-import the complete current corpus; Transept diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json > delta.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2: feed delta_block_ids VERBATIM into a group run; only those blocks translate
jq -n --slurpfile d delta.json \
  '{document_id: $d[0].master_document_id, template_id: "end_to_end",
    target_languages: "all", block_ids: $d[0].delta_block_ids}' \
| curl -s -X POST $BASE/group-runs \
    -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" --data-binary @-

Niezmienione ciągi zachowują swoje tłumaczenia i status weryfikacji; poprawienie jednego ciągu kosztuje tyle, co jeden ciąg. (Przekaż run: {template_id} bezpośrednio w żądaniu ponownego importu, aby przetworzyć różnice w tym samym wywołaniu). To odpowiednik funkcji Uruchom tylko dla zmian dostępny po stronie API. W przypadku dokumentów tekstowych, w których zmieniło się źródło, endpoint POST /documents/{id}/resync-source ponownie dopasowuje bloki: te niezmienione zachowują tłumaczenia, zmienione tracą aktualność, a przebieg ograniczony do zmian obejmuje wyłącznie te ostatnie. Ponowna synchronizacja wiąże się z ponownym przetworzeniem zapisanego pliku źródłowego, dlatego źródła należy edytować poprzez ścieżkę importu, a nie przez modyfikowanie pojedynczych bloków.

Asystenci AI (MCP)

Ten sam cykl, co w przypadku narzędzi agentowych, pod adresem https://app.transept.ai/api/public/v1/mcp: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. Połączenie wykorzystuje protokół OAuth (wymagana zgoda w przeglądarce, bez konieczności wklejania klucza; w trybie headless działa token Bearer). Narzędzia respektują nadane uprawnienia, a każda operacja zużywająca słowa najpierw zwraca wycenę, którą asystent musi jawnie potwierdzić. Konfiguracja po stronie klienta: Podłącz swojego asystenta AI.

FAQ

Czy wyceny, ponowne importy lub zaimportowane tłumaczenia zużywają słowa?

Nie. Wyceny są bezpłatne i nie niosą żadnych skutków ubocznych. Ponowny import katalogu również nic nie kosztuje (serwer sam wylicza różnice), a tłumaczenia już zawarte w plikach są traktowane jako gotowe i importowane bezpłatnie. Słowa są naliczane tylko wtedy, gdy Transept tłumaczy coś za Ciebie. Maksymalne szacunki są korygowane do poziomu faktycznego zużycia, co pozwala na zwolnienie niewykorzystanej rezerwy.

Czy automatyzacja może pominąć etapy weryfikacji?

Nie. Krok przepływu pracy ustawiony na oczekiwanie na weryfikację wstrzymuje wykonanie do momentu jego zatwierdzenia: przez skrypt wywołujący endpoint gate-approve lub przez użytkownika w aplikacji. Jeśli pipeline ma działać bezobsługowo od początku do końca, należy go skonfigurować bez etapu weryfikacji. Nie istnieje żadna flaga, która pozwalałaby pominąć celowo ustawioną bramkę.

Czy API jest dostępne w planie darmowym?

Tak. Klucze API są dostępne w każdym planie, również darmowym; nie ma tu żadnych dodatkowych barier. O skali użycia decyduje wyłącznie Twój limit słów, dokładnie tak samo jak w edytorze, a miesięczna pula słów w planie darmowym działa przez API na takich samych zasadach jak wszędzie indziej.

Jak lokalizować szablony e-maili bez ich ręcznego eksportowania?

Skieruj swoją platformę e-mailową na webhooka: treść szablonu przesłana w żądaniu POST staje się dokumentem, workflow go tłumaczy, a eksport zwraca tę samą strukturę HTML z gotowymi tłumaczeniami. Symbole zastępcze i składnia szablonu są chronione podczas całego procesu. Instrukcje dla poszczególnych platform znajdziesz w przewodniku po lokalizacji e-maili.

Gdzie znajdę pełną dokumentację punktów końcowych?

Interaktywna dokumentacja Swagger, wygenerowana na podstawie tej samej specyfikacji OpenAPI, którą można zaimportować do n8n, Zapier lub generatora kodu (surowy JSON). Ten przewodnik to opisowe wprowadzenie; specyfikacja stanowi kontrakt.