Lokalizacja katalogu stringów przez API

Formatem z kluczami w Transept jest .tstrings.json: lista jednostek, z których każda posiada stałe id, źródło (source) oraz opcjonalnie kontekst (context – informacja o tym, czym jest dany string i gdzie się pojawia), limit znaków (max_length) i symbole zastępcze (placeholders). Identyfikator pełni rolę kontraktu: to dzięki niemu tłumaczenia zachowują swoją tożsamość przy ponownym imporcie, stan weryfikacji zostaje zachowany, a eksport przypisuje klucze do każdego języka. Oba dodatkowe pola mają realne znaczenie: kontekst trafia do modelu jako wskazówka dla tłumacza, a limit znaków jest egzekwowany przez automatyczne skracanie tekstu i ponawianie próby.

Pliki CSV, gettext PO i XLIFF są importowane jako te same jednostki z kluczami przez aplikację lub endpoint do przesyłania; zobacz pliki stringów, aby sprawdzić, jak mapowane są poszczególne formaty. Ten artykuł opisuje obsługę tego cyklu z poziomu kodu, gdzie formatem natywnym jest .tstrings.json.

POST /documents/import-strings z katalogiem w formacie JSON. Języki docelowe są ustalane w stałej kolejności: pierwszeństwo ma parametr target_language / target_languages jawnie określony w żądaniu, w przeciwnym razie pole target_locales w nagłówku katalogu. Jeśli ich nie podano, wywołanie natychmiast kończy się błędem no_target_languages zamiast importować dokument bez języków docelowych. Wywołanie zwraca processing_job_id; odpytuj GET /document-jobs/{id}, aż import się zakończy i otrzymasz identyfikatory dokumentów.

Tłumaczenia już zawarte w pliku (targets: {de: "…"}) są ustawiane jako aktywne tłumaczenia poszczególnych stringów – bezpłatnie i bez konieczności uruchamiania procesu. Natychmiast zasilają one też Twoją pamięć tłumaczeniową. Działa to identycznie jak importowanie istniejących tłumaczeń przez aplikację.

# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
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}

Prześlij ponownie cały aktualny katalog do POST /documents/{id}/import-strings, a nie jego okrojoną wersję. Serwer porówna go według identyfikatorów jednostek i zwróci informację o tym, co znalazł (added, changed, unchanged, removed), oraz delta_block_ids: konkretne bloki wymagające pracy w poszczególnych wersjach językowych. Przekaż ten obiekt bez zmian jako block_ids w procesie grupowym, a przetłumaczone zostaną tylko te bloki. Możesz również przekazać parametr run bezpośrednio przy ponownym imporcie, aby zlecić tłumaczenie różnic w tym samym wywołaniu.

Niezmienione jednostki zachowują swoje tłumaczenia oraz status weryfikacji. To odpowiednik funkcji Tłumacz tylko to, co się zmieniło w API. Poprawienie jednego stringa w katalogu liczącym ich setki kosztuje tyle, co jeden string.

# 1. Re-submit the whole current catalog; the server 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
# → { 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
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end",
       "target_languages": "all", "block_ids": { "<doc_id>": ["<block id>", "…"] }}'

Wywołanie GET /documents/{id}/content?format=strings na dokumencie głównym zwraca jeden plik .tstrings.json z tłumaczeniami na wszystkie języki przypisanymi do identyfikatorów jednostek. Wystarczy jedno wywołanie, by otrzymać dane gotowe do zatwierdzenia w repozytorium lub włączenia do procesu budowania. Ten sam endpoint obsługuje wersje w poszczególnych językach (markdown, html, csv, xliff, tmx), gdy potok przetwarzania wymaga konkretnego formatu danych; pełną tabelę znajdziesz w artykule Automatyzacja Transept przez API.

W przypadku katalogów przesłanych jako CSV, PO lub XLIFF, eksport do pliku oryginalnego uzupełnia zamiast tego komórki i wpisy w Twoim własnym pliku (zachowując jego strukturę co do bajta, ale z dodanymi tłumaczeniami). Dzięki temu plik można wczytać bezpośrednio do systemu, z którego pochodzi.

curl -s "$BASE/documents/<master>/content?format=strings" \
  -H "Authorization: Bearer $KEY"
# → one .tstrings.json with every language keyed by unit id