# Языки ответа

> Язык в имени поля, параметр lang и что пока есть только на одном языке.

> Оглавление документации для агентов: https://kinodata.space/ru/llms.txt — вся документация одним файлом: https://kinodata.space/ru/llms-full.txt

API отдаёт тексты на русском и английском. Язык каждого текстового поля указан в его имени, а параметр `lang` оставляет в ответе один язык.

## Язык в имени поля

Каждое текстовое поле заканчивается на `_ru` или `_en`: `title_ru`, `kind_label_en`, `name_ru`. Без `lang` приходят обе половины:

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,type" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Ответ `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://ru.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "title": {
    "title_ru": "Начало",
    "title_en": "Inception",
    "title_original": "Inception"
  },
  "type": {
    "kind": "movie",
    "is_series": false,
    "status": "released",
    "kind_label_ru": "Фильм",
    "kind_label_en": "Movie",
    "status_label_ru": "Вышел",
    "status_label_en": "Released"
  }
}
```

Имена полей не меняются никогда: `title_en` — всегда английское название, в любом ответе и с любым `lang`. Разбирайте ответ по именам полей, а не по языку запроса.

## Один язык: lang

`lang=ru` оставляет поля `_ru`, `lang=en` — поля `_en`. Остальные поля ответа не меняются.

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,type" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Ответ `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://en.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "title": {
    "title_en": "Inception",
    "title_original": "Inception"
  },
  "type": {
    "kind": "movie",
    "is_series": false,
    "status": "released",
    "kind_label_en": "Movie",
    "status_label_en": "Released"
  }
}
```

`lang` принимает только `ru` и `en`. Другое значение — ошибка `400`. Передавать `lang` можно в любой запрос: там, где текстов нет (`/ids`, `/meta/stats`), он ничего не меняет.

## Перевода нет — null

Если текста на нужном языке нет, поле равно `null`. API не подставляет вместо него другой язык или оригинал: что показать, решаете вы. Для названия разумно взять `title_original`, для описания — текст на другом языке с пометкой.

## Что не зависит от языка

Поля без суффикса одинаковы на любом языке: ID, `slug`, `kind`, коды стран, даты, числа, `title_original`, названия компаний.

Суффикс `_ru` в фильтрах дат означает регион, а не язык: `premiere_ru` — премьера в России.

## Что сейчас есть только на одном языке

На обоих языках приходят названия, описания, жанры, страны, метки настроения и ключевые слова, церемонии и номинации наград, подборки и подписи всех перечислений. Пока на одном языке:

| что | язык | что видно в ответе |
|---|---|---|
| Факты, вопросы и цитаты — `/titles/{type}/{id}/texts` | русский | `text_en` равно `null` |
| Биография и место рождения человека — [карточка человека](https://kinodata.space/ru/docs/persons/card.md) | английский, из TMDB; русская биография — у единиц | `biography_ru` и `birthplace_ru` почти всегда `null` |
| Сводка наград | два разных текста: `summary_kinorium_ru` от Кинориума и `summary_imdb_en` от IMDb | это не перевод друг друга |
| Название франшизы — `franchise.name` | английский | поле пока без суффикса |

Факты с `lang=en` приходят без текста — так видно, что перевода ещё нет:

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=fact" \
  --data-urlencode "limit=1" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/texts"
```

Ответ `200`:

```json
{
  "counts": {
    "fact": 37,
    "faq": 16,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "fact_kind": "general",
      "is_spoiler": false,
      "kind": "fact",
      "ord": 0,
      "text_en": null
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 37
}
```

Когда перевод появится, он придёт в `*_en`, а ваш код менять не придётся.

## Английские названия и постеры

- `title_en` — только настоящее английское название. Оригинальное название неанглоязычного фильма или транслитерация туда не попадают: тогда `title_en` равно `null`, а название на языке оригинала лежит в `title_original`.
- `poster_url_en` — постер с надписями на английском. Если такого нет — `null`. `poster_url_ru` — постер для русской витрины.
- Ссылки на Кинориум с `lang=en` ведут на английскую версию сайта, `en.kinorium.com`.

## Дальше

- [Списки и пагинация](https://kinodata.space/ru/docs/lists.md) — как устроены все списки API.
- [ID во всех каталогах](https://kinodata.space/ru/docs/ids.md) — связка ID одного тайтла.