# Response languages

> The language in the field name, the lang parameter and what is in one language only.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

The API serves text in Russian and English. The language of every text field is in its name, and the `lang` parameter keeps just one language in the response.

## The language is in the field name

Every text field ends in `_ru` or `_en`: `title_ru`, `kind_label_en`, `name_ru`. Without `lang` you get both halves:

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

Response `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"
  }
}
```

Field names never change: `title_en` is always the English title, in every response and with any `lang`. Read the response by field name, not by the language you asked for.

## One language: lang

`lang=en` keeps the `_en` fields, `lang=ru` keeps the `_ru` fields. Everything else in the response stays the same.

```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"
```

Response `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` accepts only `ru` and `en`. Any other value returns `400`. You can send `lang` with any request: where a response has no text (`/ids`, `/meta/stats`), it changes nothing.

## No translation means null

When there is no text in the requested language, the field is `null`. The API never falls back to another language or the original: what to show instead is your call. For a title, `title_original` is a sensible choice; for an overview, the text in the other language with a note.

## What doesn't depend on language

Fields without a suffix are the same in every language: IDs, `slug`, `kind`, country codes, dates, numbers, `title_original`, company names.

In date filters the `_ru` suffix means the region, not the language: `premiere_ru` is the premiere in Russia.

## What is in one language only today

Both languages cover titles, overviews, genres, countries, mood tags and keywords, award ceremonies and categories, collections and the labels of every enum. Still in one language:

| what | language | what you see |
|---|---|---|
| Facts, FAQ and quotes: `/titles/{type}/{id}/texts` | Russian | `text_en` is `null` |
| A person's biography and birthplace: the [person card](https://kinodata.space/en/docs/persons/card.md) | English, from TMDB; only a handful of Russian biographies | `biography_ru` and `birthplace_ru` are almost always `null` |
| Awards summary | two different texts: `summary_kinorium_ru` from Kinorium and `summary_imdb_en` from IMDb | not translations of each other |
| Franchise name: `franchise.name` | English | the field has no suffix yet |

With `lang=en`, facts come back without text, which shows the translation isn't there yet:

```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"
```

Response `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
}
```

When a translation arrives it lands in `*_en`, and your code doesn't need to change.

## English titles and posters

- `title_en` holds only a real English title. The original title of a non-English film or a transliteration never goes there: in that case `title_en` is `null` and the original-language title is in `title_original`.
- `poster_url_en` is a poster with English lettering; `null` if there is none. `poster_url_ru` is the poster for a Russian storefront.
- With `lang=en`, Kinorium links point to the English site, `en.kinorium.com`.

## Next

- [Lists and pagination](https://kinodata.space/en/docs/lists.md): how every list in the API works.
- [IDs in every catalog](https://kinodata.space/en/docs/ids.md): one title's linked IDs.