API перакладаў

Эндпоінты перакладаў вяртаюць усе моўныя версіі запісу ў адным адказе: title або name, overview, tagline і homepage для фільмаў і серыялаў, name і overview для эпізодаў. Кожны радок нясе 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_keyзапытадзін з двух
    Ваш ключ. Выкарыстоўвайце яго або загаловак 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'. Пазначайце ў інтэрфейсе тэкст з запасной мовы, каб карыстальнік разумеў, чаму ўкраінская старонка паказвае англійскі сюжэт.

Translations ці параметр 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.