API перекладів

Ендпоінти перекладів повертають усі мовні версії запису в одній відповіді: назву, опис, слоган і homepage для фільмів та серіалів, назву й опис для серій. Кожен рядок містить iso_639_1, iso_3166_1 та english_name. Використовуйте їх, щоб читати мови, яких не обслуговує параметр language, або будувати ланцюжок запасних мов.

Оновлено Відкрити в Markdown

Отримання перекладів фільму

GET /3/movie/{movie_id}/translations повертає по одному рядку на кожну мову, для якої є текст фільму. Кожен рядок містить об'єкт data з перекладеними полями. Виклик не приймає параметра мови, бо головна ідея в тому, щоб побачити всі мови одразу.

Приклад знаходить російський рядок і виводить його назву та початок опису.

bashjspyphpgo
curl -s "https://api.amodb.dev/3/movie/550/translations" \
  -H "Authorization: Bearer $AMODB_KEY"
const url = 'https://api.amodb.dev/3/movie/550/translations';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { translations } = await res.json();
const ru = translations.find((t) => t.iso_639_1 === 'ru');
console.log(ru ? `${ru.data.title}: ${ru.data.overview.slice(0, 80)}` : 'no Russian row');
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550/translations",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
ru = next((t for t in r.json()["translations"] if t["iso_639_1"] == "ru"), None)
print(f"{ru['data']['title']}: {ru['data']['overview'][:80]}" if ru else "no Russian row")
<?php
$ch = curl_init('https://api.amodb.dev/3/movie/550/translations');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
foreach (json_decode($body, true)['translations'] as $t) {
    if ($t['iso_639_1'] === 'ru') {
        echo $t['data']['title'], ': ', mb_substr($t['data']['overview'], 0, 80), PHP_EOL;
        exit;
    }
}
echo 'no Russian row', PHP_EOL;
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Translations struct {
	Translations []struct {
		ISO6391 string `json:"iso_639_1"`
		Data    struct {
			Title    string `json:"title"`
			Overview string `json:"overview"`
		} `json:"data"`
	} `json:"translations"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/translations", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var t Translations
	if err := json.NewDecoder(res.Body).Decode(&t); err != nil {
		panic(err)
	}
	for _, row := range t.Translations {
		if row.ISO6391 == "ru" {
			text := []rune(row.Data.Overview)
			if len(text) > 80 {
				text = text[:80]
			}
			fmt.Printf("%s: %s\n", row.Data.Title, string(text))
			return
		}
	}
	fmt.Println("no Russian row")
}

Параметри

  • movie_idшляхобов'язковий
    Числовий id фільму, наприклад 550.
  • api_keyqueryодин із двох
    Ваш ключ. Використовуйте його або заголовок Authorization: Bearer.

Поля відповіді

ПолеТипПримітки
idціле числоID фільму.
translationsмасивРядки по одному на мову, для якої є текст, відсортовані за кодом мови. Фільм 550 повертає 50 рядків.
translations[].iso_3166_1рядокКод країни, що відповідає мові, наприклад US для en або BR для pt. Для мов поза 14 обслуговуваними повторює код мови великими літерами.
translations[].iso_639_1рядокКод мови, наприклад ru або pt. Унікальний у масиві.
translations[].nameрядокНазва мови, записана цією мовою.
translations[].english_nameрядокНазва мови англійською.
translations[].dataоб'єктПерекладені поля. Ключі залежать від ресурсу, див. таблицю нижче.

Приклад відповіді

Показано два з 50 рядків, описи скорочено.

JSON
{
  "id": 550,
  "translations": [
    {
      "iso_3166_1": "US",
      "iso_639_1": "en",
      "name": "English",
      "english_name": "English",
      "data": {
        "title": "Fight Club",
        "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy....",
        "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
        "tagline": "Mischief. Mayhem. Soap.",
        "runtime": 0
      }
    },
    {
      "iso_3166_1": "RU",
      "iso_639_1": "ru",
      "name": "Русский",
      "english_name": "Russian",
      "data": {
        "title": "Бойцовский клуб",
        "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажд...",
        "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
        "tagline": "«Интриги. Хаос. Мыло»",
        "runtime": 0
      }
    }
  ]
}

В amodb runtime у рядку перекладу завжди дорівнює 0. Читайте тривалість із запису деталі фільму.

Ендпоінти перекладів і ключі data

Усі шляхи мають спільну базу https://api.amodb.dev/3. Кожен повертає id та масив translations із рядками такої самої форми, як вище. Змінюються лише ключі всередині data.

Метод і шляхКлючі data
GET /movie/{movie_id}/translationstitle, overview, homepage, tagline, runtime (завжди 0)
GET /tv/{series_id}/translationsname, overview, homepage, tagline
GET /tv/{series_id}/season/{season_number}/translationsнемає, масив завжди порожній
GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/translationsname, overview

Записи серіалів містять приблизно стільки ж мов, скільки й фільми. Рядки серій охоплюють лише ті обслуговувані мови, для яких є текст цієї серії, від 2 до 14 у перевірених зразках. Відсутній ключ сприймайте як порожнє значення, а невідомі ключі ігноруйте. Батьківські записи дивіться в розділі серіали.

amodb не пропонує перекладів для персон чи колекцій. Біографія персони залежить від параметра language виклику деталей персони, а опис колекції повертається як збережений.

Запасний варіант, коли тексту немає

Назва може існувати у 14 мовах і все одно мати порожній опис мовою, яку обрав користувач. Пройдіть ланцюжок мов, візьміть перше непорожнє значення й запам'ятайте, з якої мови воно прийшло.

JavaScript
function pickText(translations, wanted, field) {
  for (const code of [...wanted, 'en']) {
    const row = translations.find((t) => t.iso_639_1 === code);
    const value = row?.data?.[field];
    if (value) return { code, value };
  }
  return null;
}

// Prefer Ukrainian, then Russian, then English.
// const hit = pickText(translations, ['uk', 'ru'], 'overview');

Для серіалу передайте 'name' як поле замість 'title'. Позначайте в інтерфейсі текст із запасної мови, щоб користувач розумів, чому українська сторінка показує англійський опис.

Переклади чи параметр language

ПотребаЩо використати
Показати одну мову одному користувачевіlanguage у виклику деталей
Вивести всі мови назви в редакторіЦей ендпоінт
Прочитати мову, якої language не обслуговує, як-от jaЦей ендпоінт, обирайте рядок за iso_639_1
Перевірити, для яких із 14 обслуговуваних мов є текстЦей ендпоінт, порівнюйте iso_639_1
Побудувати посилання на альтернативні мови сторінкиЦей ендпоінт, читайте наявні коди

Теги, які приймає language, дивіться в розділі мови. Будь-який інший тег у виклику деталей повертається до англійської.

Помилки

HTTPstatus_codeКоли
4017Ключ відсутній або хибний.
40236Термін дії тарифу закінчився.
40434Немає сезону чи серії з таким id або id не є числом.
40537Ви використали метод запису на шляху перекладів.
42925Ви перевищили ліміт запитів на хвилину. Зачекайте стільки секунд, скільки вказано в Retry-After.

Неіснуючий id фільму чи серіалу на цьому шляху не помилка: він відповідає 200 із "translations": [], тоді як шлях деталей відповідає 404. Докладніше про помилки та ліміти запитів.

Практичні нотатки

  • Один виклик замінює до 14 викликів деталей. Використовуйте його, коли потрібно більше двох мов однієї назви.
  • Рядки відсортовано за кодом мови, а це не порядок пріоритету. Обирайте рядки за iso_639_1, ніколи за позицією в масиві.
  • Виклики типу деталей кешуються на edge на 6 годин, тож клієнтський кеш такої самої тривалості нічого не коштує у свіжості.
  • Оригінальні назви іншими писемностями, як-от японською чи корейською, завжди доступні в original_title та original_name запису деталей.
  • Щоб додати переклади до виклику деталей, передайте append_to_response=translations і читайте той самий масив у відповіді. Це працює для фільмів, серіалів і серій. Доданий блок не має id.