Automatyzacja Transept za pomocą API

Utwórz osobisty klucz API w sekcji Ustawienia → Deweloper. Jest on dostępny w każdym planie, również darmowym – nie ma osobnych barier, a o użyciu decyduje limit słów. Nadaj kluczowi nazwę, opcjonalnie ustaw datę wygaśnięcia i skopiuj sekret, gdy zostanie wyświetlony: pojawia się on tylko raz i nie można go później odzyskać. Klucz można unieważnić w dowolnym momencie na tej samej stronie.

Żądania są uwierzytelniane za pomocą klucza w nagłówku Authorization: Bearer tsk_live_… – wyłącznie w nagłówku, nigdy w adresie URL.

Utwórz dokument z surowego tekstu, HTML lub Markdown albo prześlij plik – obsługiwane są te same formaty, co w aplikacji. Możesz również zaimportować tabelę ciągów znaków (.tstrings.json): ustrukturyzowany format dla tekstów interfejsu lub ciągów w grach, w którym każdy ciąg jest jednostką ze stałym kluczem i własnym kontekstem – notatką o tym, czym jest, gdzie się pojawia, limitem znaków oraz znaczeniem symboli zastępczych. Wszystko to trafia do modelu, symbole zastępcze takie jak {name} są chronione przed usunięciem lub zmianą nazwy, a formy liczby mnogiej są rozwijane zależnie od języka (jedna forma angielska staje się dwiema w niemieckim i czterema w ukraińskim). Wszelkie tłumaczenia zawarte już w pliku są importowane w niezmienionej formie, bezpłatnie i natychmiast zasilają pamięć tłumaczeniową.

Uruchomienie grupowe pozwala na tłumaczenie na wiele języków naraz. Podaj nazwę dokumentu, Workflow lub szablon do uruchomienia oraz języki docelowe; Transept utworzy brakujące wersje językowe i uruchomi Workflow dla każdej z nich. Całość śledzona jest pod jednym identyfikatorem – odpytuj go o postępy w poszczególnych językach i o to, czy wymagana jest weryfikacja.

W przypadku powtórnych uruchomień prześlij ponownie bieżący plik tabeli ciągów znaków, a Transept ustali, co się zmieniło: niezmienione ciągi zachowują swoje tłumaczenia (oraz wykonane już weryfikacje), a proces obejmuje tylko nowe lub faktycznie zmienione jednostki – to odpowiednik funkcji Uruchom tylko dla zmian w API. Wywołanie tworzące zadanie akceptuje również nagłówek Idempotency-Key, dzięki czemu ponowna próba po chwilowym problemie z siecią zwraca pierwotny wynik zamiast tworzenia drugiego dokumentu i naliczenia kolejnej opłaty.

Zamiast odpytywania, zarejestruj adres URL, a Transept wyśle zdarzenie, gdy uruchomienie zakończy się sukcesem lub błędem, gdy weryfikacja będzie gotowa do sprawdzenia, gdy przetwarzanie przesłanego pliku dobiegnie końca oraz gdy eksport będzie gotowy. Każde powiadomienie zawiera nagłówek HMAC-SHA256 X-Transept-Signature: t=…,v1=…, dzięki czemu odbiorca może zweryfikować, czy faktycznie pochodzi ono od nas. W przypadku braku odpowiedzi punktu końcowego próby są ponawiane z opóźnieniem (backoff), zanim zostanie on wyłączony.

Workflow może być również wyzwalany automatycznie przez automatyzację bazy danych Notion: skieruj webhook automatyzacji na adres URL wyzwalacza, a Transept uruchomi Workflow na stronie, która uległa zmianie. Haczyk polega na tym, że webhook z Notion nigdy nie przesyła treści strony – informuje jedynie, która strona aktywowała wyzwalacz. Transept odczytuje tę stronę poprzez Twoje połączenie z Notion, więc muszą zostać spełnione dwa warunki. W przeciwnym razie każde wywołanie zostanie odrzucone z powodu błędu dostępu, a na karcie wyzwalacza pojawi się komunikat „nie udało się odczytać strony Notion”:

• Połącz Notion w Transept – w sekcji Ustawienia → Integracje. To jednorazowe powiązanie OAuth, dzięki któremu Transept może odczytywać dane w Twoim imieniu.
• Udostępnij integracji źródłową bazę danych wewnątrz Notion – otwórz bazę danych (lub stronę), kliknij menu •••, wybierz Połączenia i dodaj Transept. Samo powiązanie Notion w Ustawieniach nie daje dostępu do konkretnej bazy danych; bez tego kroku połączenie jest aktywne, ale strona pozostaje nieczytelna.
• Wyzwalaj przy zmianie właściwości, a nie tylko przy edycji treści. Automatyzacje w Notion są wyzwalane przez zmiany właściwości (oraz dodanie strony), więc sama edycja treści strony może niczego nie uruchomić. Niezawodnym sposobem jest właściwość Status, którą monitoruje automatyzacja – zmień jej wartość (np. na „Ready to translate”), a ta zmiana aktywuje wyzwalacz.

Pełna lista punktów końcowych jest publikowana jako specyfikacja OpenAPI, którą można zaimportować do n8n, Zapiera lub generatora kodu: można ją przeglądać pod adresem /public/v1/docs w API Transept lub pobrać surowy plik JSON z /public/v1/openapi.json. Uruchomienia zainicjowane przez API rozliczają Wörter dokładnie tak samo, jak edytor w aplikacji.