Jak korzystać z API TextUnited: Natychmiastowe tłumaczenie i tworzenie projektów

API Segments TextUnited daje programistom programowy sposób na natychmiastowe tłumaczenie tekstu, tworzenie projektów tłumaczeniowych oraz pobieranie przetłumaczonych segmentów. Ten przewodnik przeprowadzi Cię przez trzy główne operacje: natychmiastowe tłumaczenie, tworzenie projektu i pobieranie segmentów — z przykładami żądań i odpowiedzi dla każdej z nich.

Wymagania wstępne

Przed wykonaniem jakichkolwiek wywołań API będziesz potrzebować:

• Konta TextUnited z włączonym dostępem do API
• Ważnego tokenu Bearer — dołącz go do każdego żądania w nagłówku `Authorization: Bearer {twój_token}`
• Wszystkie żądania używają bazowego adresu URL: `https://www.textunited.com`
• Nagłówek `Content-Type` musi być ustawiony na `application/json` dla wszystkich żądań POST

Uwaga: Kody języków używają formatu IETF BCP 47 (np. `en-US`, `de-DE`, `fr-FR`). Upewnij się, że używasz prawidłowych kodów języków obsługiwanych przez TextUnited.

1. Natychmiastowe tłumaczenie

Endpoint `/segments/translation` tłumaczy segmenty tekstowe natychmiast, bez tworzenia projektu. Jest to idealne rozwiązanie do szybkich, jednorazowych tłumaczeń.

Żądanie

Wyślij żądanie POST z:

• `sourceLanguageCode`: kod języka źródłowego (np. `en-US`)
• `targetLanguages`: tablica kodów języków docelowych
• `segments`: tablica obiektów segmentów, każdy z `customId` i `content`

POST /api/private/segments/translation
Authorization: Bearer {your_token}
Content-Type: application/json

{
  "sourceLanguageCode": "en-US",
  "targetLanguages": ["de-DE", "fr-FR"],
  "segments": [
    { "customId": "seg_001", "content": "Hello, world!" },
    { "customId": "seg_002", "content": "Welcome to TextUnited." }
  ]
}

Odpowiedź

Odpowiedź zawiera przetłumaczone segmenty pogrupowane według języka docelowego. Każdy segment zawiera `customId`, `content` (przetłumaczony tekst) oraz `status` wskazujący wynik tłumaczenia.

{
  "translations": [
    {
      "languageCode": "de-DE",
      "segments": [
        { "customId": "seg_001", "content": "Hallo, Welt!", "status": "Translated" },
        { "customId": "seg_002", "content": "Willkommen bei TextUnited.", "status": "Translated" }
      ]
    },
    {
      "languageCode": "fr-FR",
      "segments": [
        { "customId": "seg_001", "content": "Bonjour, monde!", "status": "Translated" },
        { "customId": "seg_002", "content": "Bienvenue chez TextUnited.", "status": "Translated" }
      ]
    }
  ]
}

2. Tworzenie projektu

Endpoint `/segments/project` tworzy projekt tłumaczeniowy z segmentami. Możesz kontrolować, czy tłumaczenie odbywa się natychmiast, czy jest zarządzane przez tłumaczy, za pomocą flag w treści żądania.

Kluczowe flagi

instantTranslation

• `true`: segmenty są tłumaczone natychmiast przy użyciu tłumaczenia maszynowego
• `false`: projekt jest tworzony bez natychmiastowego tłumaczenia (segmenty oczekują na tłumaczenie)

managedProject (dla każdego języka docelowego)

• `true`: projekt jest zarządzany przez tłumaczy TextUnited
• `false`: projekt jest niezarządzany (samodzielny)

Żądanie

POST /api/private/segments/project
Authorization: Bearer {your_token}
Content-Type: application/json

{
  "name": "My Translation Project",
  "customId": "proj_001",
  "sourceLanguageCode": "en-US",
  "instantTranslation": false,
  "targets": [
    {
      "languageCode": "de-DE",
      "managedProject": false
    },
    {
      "languageCode": "fr-FR",
      "managedProject": false
    }
  ],
  "segments": [
    { "customId": "seg_001", "content": "Hello, world!" },
    { "customId": "seg_002", "content": "Welcome to TextUnited." }
  ]
}

Odpowiedź: Bez tłumaczenia natychmiastowego

Gdy `instantTranslation` jest ustawione na `false`, odpowiedź zawiera metadane projektu, ale segmenty nie mają jeszcze tłumaczeń. Pole `instantTranslationTranslations` będzie puste lub nieobecne.

{
  "id": 12345,
  "customId": "proj_001",
  "name": "My Translation Project",
  "sourceLanguageCode": "en-US",
  "instantTranslation": false,
  "targets": [
    {
      "languageId": 1,
      "languageCode": "de-DE",
      "managedProject": false,
      "taskId": 67890
    },
    {
      "languageId": 2,
      "languageCode": "fr-FR",
      "managedProject": false,
      "taskId": 67891
    }
  ],
  "instantTranslationTranslations": []
}

Odpowiedź: Z tłumaczeniem natychmiastowym

Gdy `instantTranslation` jest ustawione na `true`, odpowiedź zawiera przetłumaczone segmenty bezpośrednio w polu `instantTranslationTranslations`.

{
  "id": 12346,
  "customId": "proj_001",
  "name": "My Translation Project",
  "sourceLanguageCode": "en-US",
  "instantTranslation": true,
  "targets": [
    {
      "languageId": 1,
      "languageCode": "de-DE",
      "managedProject": false,
      "taskId": 67892
    }
  ],
  "instantTranslationTranslations": [
    {
      "languageCode": "de-DE",
      "segments": [
        { "customId": "seg_001", "content": "Hallo, Welt!", "status": "Translated" },
        { "customId": "seg_002", "content": "Willkommen bei TextUnited.", "status": "Translated" }
      ]
    }
  ]
}

3. Pobieranie przetłumaczonych segmentów

Po utworzeniu projektu możesz pobierać przetłumaczone segmenty za pomocą własnego identyfikatora projektu (`customId`). Jest to szczególnie przydatne, gdy `instantTranslation` było ustawione na `false` i chcesz sprawdzić postęp tłumaczenia.

Wyślij żądanie GET do: `/api/private/segments/project/{customId}/translations`, zastępując `{customId}` własnym identyfikatorem projektu.

Żądanie

GET /api/private/segments/project/{customId}/translations
Authorization: Bearer {your_token}

Odpowiedź

Odpowiedź zawiera tablicę tłumaczeń pogrupowanych według języka. Każdy obiekt języka zawiera tablicę segmentów z następującymi polami:

• `languageId`: wewnętrzny identyfikator języka
• `languageCode`: kod języka IETF (np. `de-DE`)
• `content`: przetłumaczony tekst segmentu
• `status`: stan tłumaczenia (np. `Translated`, `Pending`)
• `comments`: opcjonalne komentarze tłumacza

{
  "translations": [
    {
      "languageId": 1,
      "languageCode": "de-DE",
      "segments": [
        {
          "customId": "seg_001",
          "content": "Hallo, Welt!",
          "status": "Translated",
          "comments": null
        },
        {
          "customId": "seg_002",
          "content": "Willkommen bei TextUnited.",
          "status": "Translated",
          "comments": null
        }
      ]
    }
  ]
}

Jeśli segmenty mają status `Pending`, tłumaczenie jest nadal w toku. Możesz odpytywać ten endpoint w regularnych odstępach czasu, aż wszystkie segmenty osiągną status `Translated`.

Dokumentacja modelu danych

Ta sekcja dokumentuje pełne modele danych C# używane przez API Segments TextUnited. Zrozumienie tych modeli pomoże Ci poprawnie konstruować żądania i interpretować odpowiedzi.

SegmentProject

Obiekt projektu najwyższego poziomu zwracany przez endpointy tworzenia projektu i pobierania.

• Id: wewnętrzny identyfikator projektu (liczba całkowita)
• CustomId: Twój własny identyfikator projektu (ciąg znaków)
• TaskId: identyfikator powiązanego zadania (liczba całkowita)
• Name: nazwa projektu (ciąg znaków)
• SourceLanguageCode: kod języka źródłowego IETF (ciąg znaków)
• InstantTranslation: czy użyto tłumaczenia natychmiastowego (wartość logiczna)
• Targets: lista obiektów `SegmentProjectTarget` (jeden na język docelowy)
• InstantTranslationTranslations: lista obiektów `InstantTranslationTranslations` (wypełniona tylko gdy `instantTranslation: true`)

SegmentProjectTarget

Reprezentuje jeden język docelowy w projekcie tłumaczeniowym.

• LanguageId: wewnętrzny identyfikator języka TextUnited (liczba całkowita)
• LanguageCode: kod języka IETF (ciąg znaków)
• ManagedProject: czy projekt jest zarządzany przez tłumaczy (wartość logiczna)
• TaskId: identyfikator zadania tłumaczeniowego dla tego języka (liczba całkowita)
• UseTranslationMemory: czy używana jest pamięć tłumaczeniowa (wartość logiczna)
• UseMachineTranslation: czy używane jest tłumaczenie maszynowe (wartość logiczna)

Uwaga: Flagi `UseTranslationMemory` i `UseMachineTranslation` są ustawiane przez konfigurację usługi TextUnited i mogą nie być bezpośrednio kontrolowane przez żądanie API.

ProjectTeamMember

Reprezentuje członka zespołu przypisanego do projektu tłumaczeniowego.

• UserId: identyfikator użytkownika (liczba całkowita)
• Email: adres e-mail członka zespołu (ciąg znaków)
• Role: rola w projekcie (np. `Translator`, `Reviewer`) (ciąg znaków)
• LanguageId: identyfikator języka, do którego przypisany jest członek (liczba całkowita)

Uwaga: Jeden użytkownik może mieć wiele ról w projekcie (np. tłumacz dla jednego języka i recenzent dla innego).

InstantTranslationTranslations

Grupuje przetłumaczone segmenty według języka docelowego, gdy używane jest tłumaczenie natychmiastowe.

• LanguageCode: kod języka docelowego IETF (ciąg znaków)
• Segments: lista obiektów `InstantTranslationSegment`

InstantTranslationSegment

Reprezentuje pojedynczy przetłumaczony segment w odpowiedzi tłumaczenia natychmiastowego.

• CustomId: Twój własny identyfikator segmentu (ciąg znaków)
• Content: przetłumaczony tekst (ciąg znaków)
• Status: stan tłumaczenia (ciąg znaków, np. `Translated`)

InstantTranslationSegmentTarget

Reprezentuje przetłumaczony segment dla konkretnego języka docelowego w kontekście pobierania segmentów projektu.

• CustomId: Twój własny identyfikator segmentu (ciąg znaków)
• Content: przetłumaczony tekst (ciąg znaków)
• Status: stan tłumaczenia (ciąg znaków)
• Comments: opcjonalne komentarze tłumacza (ciąg znaków lub null)

Podsumowanie

API Segments TextUnited oferuje elastyczny sposób integracji tłumaczeń z Twoją aplikacją. Niezależnie od tego, czy potrzebujesz natychmiastowych tłumaczeń jednorazowych, czy zarządzanych projektów tłumaczeniowych z wieloma językami docelowymi, API zapewnia proste endpointy do tworzenia projektów, pobierania tłumaczeń i śledzenia postępu.

Korzystając z własnych identyfikatorów projektów (`customId`), możesz łatwo mapować projekty TextUnited na własne struktury danych i odpytywać o tłumaczenia w dowolnym momencie. Pełna dokumentacja modelu danych w tej sekcji powinna pomóc Ci zrozumieć kształt odpowiedzi i odpowiednio zaplanować integrację.