Jak korzystać z API TextUnited: automatyczne 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://api.textunited.com
• Nagłówek Content-Type musi być ustawiony na application/json-patch+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 treścią (text lub HTML) oraz pocjonalne notatki

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 przez tłumacza)

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ę.