# API delle traduzioni > Gli endpoint delle traduzioni restituiscono ogni versione linguistica di un record in una sola risposta: titolo o nome, trama, slogan e sito per film e serie, nome e trama per gli episodi. Ogni riga porta iso_639_1, iso_3166_1 ed english_name. Usalo per le lingue che language non serve o per costruire una catena di ripiego. ## Endpoint `GET /3/movie/{movie_id}/translations` ```bash curl "https://api.amodb.dev/3/movie/550/translations" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```json { "id": 550, "translations": [ { "iso_3166_1": "AR", "iso_639_1": "ar", "name": "العربية", "english_name": "Arabic", "data": { "title": "نادي القتال", "overview": "يعيش موظف مكتبي يعاني من الأرق والملل حياة روتينية فارغة، إلى أن يلتقي بالرجل الغامض تايلر ديردن، الذي يختلف عنه تمامًا ويؤمن بأن التحرر من قيود المجتمع يبدأ برفض الحياة التقليدية. تنشأ بينهما صداقة غريبة تقودهما إلى تأسيس نادٍ سري يتجمع في...", "homepage": "", "tagline": "نادي القتال هو نادي يوجد في العقل الباطن لكل واحد منا !", "runtime": 0 } }, { "iso_3166_1": "AZ", "iso_639_1": "az", "name": "Azərbaycan", "english_name": "Azerbaijani", "data": { "title": "Döyüş Klubu", "overview": "Xəyalları olmayan bir gənc yuxusuzluğa qarşı mübarizə aparır, bəlkə də boz və gündəlik həyatı ilə cansıxıcılığının nəticəsidir. Təyyarə gəzintisində o, çox xüsusi bir fəlsəfəyə sahib olan xarizmatik sabun satıcısı Tyler Durden ilə tanış olu...", "homepage": "", "tagline": "", "runtime": 0 } }, { "iso_3166_1": "BY", "iso_639_1": "be", "name": "Беларуская", "english_name": "Belarusian", "data": { "title": "Байцоўскі клуб", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the wa...", "homepage": "", "tagline": "", "runtime": 0 } } ] } ``` ## Ottenere le traduzioni di un film `GET /3/movie/{movie_id}/translations` restituisce una riga per ogni lingua che ha testo per il film. Ogni riga contiene un oggetto `data` con i campi tradotti. La chiamata non accetta alcun parametro di lingua, perché lo scopo è proprio vedere tutte le lingue insieme. L'esempio trova la riga in russo e ne stampa il titolo e l'inizio della trama. ```bash curl -s "https://api.amodb.dev/3/movie/550/translations" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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'); ``` ```python 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 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; ``` ```go 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") } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | ---------- | -------- | ------------ | ------------------------------------------------------------- | | `movie_id` | percorso | sì | ID numerico del film, per esempio `550`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | ### Campi della risposta | Campo | Tipo | Note | | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | intero | L'ID del film. | | `translations` | array | Una riga per ogni lingua che ha testo, ordinata per codice lingua. Il film 550 restituisce 50 righe. | | `translations[].iso_3166_1` | stringa | Codice paese che accompagna la lingua, come `US` per `en` o `BR` per `pt`. Per le lingue fuori dalle 14 servite ripete il codice della lingua in maiuscolo. | | `translations[].iso_639_1` | stringa | Codice lingua come `ru` o `pt`. Univoco nell'array. | | `translations[].name` | stringa | La lingua scritta in quella lingua. | | `translations[].english_name` | stringa | Il nome della lingua in inglese. | | `translations[].data` | oggetto | I campi tradotti. Le chiavi dipendono dalla risorsa, vedi la tabella qui sotto. | ### Risposta di esempio Sono mostrate due delle 50 righe, e le trame sono tagliate. ```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 } } ] } ``` In amodb `runtime` vale sempre 0 in una riga di traduzione. Leggi la durata dalla scheda dei [dettagli del film](https://amodb.dev/it/movies/). ## Endpoint delle traduzioni e le loro chiavi di dati Tutti i percorsi condividono la base `https://api.amodb.dev/3`. Ognuno restituisce `id` e un array `translations` con la forma di riga qui sopra. Cambiano solo le chiavi dentro `data`. | Metodo e percorso | Chiavi di `data` | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `GET /movie/{movie_id}/translations` | `title`, `overview`, `homepage`, `tagline`, `runtime` (sempre 0) | | `GET /tv/{series_id}/translations` | `name`, `overview`, `homepage`, `tagline` | | `GET /tv/{series_id}/season/{season_number}/translations` | nessuna, l'array è sempre vuoto | | `GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/translations` | `name`, `overview` | I record delle serie elencano più o meno tante lingue quante i film. Le righe degli episodi coprono solo le lingue servite che hanno testo per quell'episodio, da 2 a 14 nei campioni controllati. Tratta una chiave mancante come un valore vuoto, e ignora le chiavi che non conosci. Vedi [serie TV](https://amodb.dev/it/tv-series/) per i record padre. amodb non offre traduzioni per persone o collezioni. La biografia di una persona segue il parametro `language` della chiamata dei dettagli della persona, e la trama di una collezione arriva come salvata. ## Ripiegare quando il testo manca Un titolo può esistere in 14 lingue e avere comunque una trama vuota in quella scelta dal tuo utente. Scorri una catena di lingue, prendi il primo valore non vuoto e ricorda da quale lingua viene. ```js 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'); ``` Per una serie, passa `'name'` come campo invece di `'title'`. Segnala nella tua interfaccia il testo preso da una lingua di ripiego, così l'utente capisce perché una pagina in ucraino mostra una sinossi in inglese. ## Translations o parametro language | Esigenza | Cosa usare | | ------------------------------------------------------ | ----------------------------------------------- | | Mostrare una lingua a un utente | `language` sulla chiamata dei dettagli | | Elencare tutte le lingue di un titolo in un editor | Questo endpoint | | Leggere una lingua che `language` non serve, come `ja` | Questo endpoint, scegli la riga per `iso_639_1` | | Controllare quali delle 14 lingue servite hanno testo | Questo endpoint, confronta `iso_639_1` | | Costruire link a lingue alternative per una pagina | Questo endpoint, leggi i codici presenti | Per i tag che `language` accetta, vedi [lingue](https://amodb.dev/it/languages/). Qualsiasi altro tag ripiega sull'inglese in una chiamata di dettagli. ## Errori | HTTP | status_code | Quando | | ---- | ----------- | ------------------------------------------------------------------------ | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | Nessuna stagione o episodio con quell'ID, o un ID che non è un numero. | | 405 | 37 | Hai usato un metodo di scrittura su un percorso di traduzioni. | | 429 | 25 | Hai superato le richieste al minuto. Attendi i secondi di `Retry-After`. | Un ID di film o serie che non esiste non è un errore su questo percorso: risponde 200 con `"translations": []`, mentre il percorso dei dettagli risponde 404. Altro nelle pagine [errori](https://amodb.dev/it/errors/) e [limiti di richieste](https://amodb.dev/it/rate-limits/). ## Note pratiche - Una chiamata sostituisce fino a 14 chiamate di dettagli. Usala quando ti servono più di due lingue dello stesso titolo. - Le righe sono ordinate per codice lingua, che non è un ordine di priorità. Scegli le righe per `iso_639_1`, mai per posizione nell'array. - Le chiamate di tipo dettagli restano in cache sull'edge per 6 ore, quindi una cache client della stessa durata non costa nulla in freschezza. - I titoli originali in altre scritture, come giapponese o coreano, sono sempre disponibili in `original_title` e `original_name` nella scheda dei dettagli. - Per aggiungere le traduzioni a una chiamata di dettagli, passa `append_to_response=translations` e leggi lo stesso array dalla risposta. Funziona per film, serie ed episodi. Il blocco aggiunto non ha un `id`. ## Domande e risposte ### Quando uso translations invece del parametro language? Usa language quando mostri una sola lingua a un utente. Usa translations quando ti servono più lingue dello stesso titolo insieme, per esempio per una schermata di editing, pagine in lingue alternative o un controllo della copertura. Restituisce anche lingue che language non serve, come ja o de. ### Qual è la differenza tra iso_639_1 e iso_3166_1? iso_639_1 è il codice della lingua, come pt. iso_3166_1 è il paese che lo accompagna, come BR. Per le lingue fuori dalle 14 servite ripete il codice della lingua in maiuscolo, per esempio DA per da, quindi fai sempre la corrispondenza su iso_639_1. ### Perché un campo è vuoto dentro data? Una stringa vuota o uno zero significa che per quel campo in quella lingua non esiste testo. Non mostrarlo. Ripiega sulla lingua successiva della tua catena, di solito l'inglese, o sul titolo originale. ### Quali lingue copre l'endpoint? I record di film e serie elencano tutte le lingue che il catalogo possiede, spesso da 40 a 80 righe. Questo include le 14 servite: en, ru, uk, be, zh, pt, bg, he, cs, ro, fr, pl, it ed es. Gli episodi ne elencano solo alcune tra queste 14. ## Pagine correlate - [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue. - [API delle serie TV](https://amodb.dev/it/tv-series/): API serie TV con gli stessi percorsi e JSON di TMDB v3. Ottieni una serie per ID con stagioni, emittenti e prossimo episodio, più classificazioni e piattaforme. - [API dei dettagli della persona](https://amodb.dev/it/people/): API dettagli persona con gli stessi percorsi e JSON di TMDB v3. Ottieni attore o troupe per ID, con biografia, filmografia, ID esterni e lista dei popolari. - [API delle collezioni](https://amodb.dev/it/collections/): API collezioni di film con percorsi TMDB v3: recupera una saga per ID con tutte le sue parti, leggi belongs_to_collection su un film e cerca per nome. - [Lingue](https://amodb.dev/it/languages/): amodb serve titoli, trame e nomi in 14 lingue. Passa un tag in stile TMDB come ru-RU o pt-BR in language; qualsiasi altro tag ripiega sull'inglese. - [API di metadati film multilingue](https://amodb.dev/it/multilingual-movie-metadata-api/): API di metadati film in 14 lingue. Usa i tag di lingua TMDB, leggi tutte le traduzioni, ripiega sull'inglese e gestisci l'ebraico da destra a sinistra. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/translations/