> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcdn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Languages

> How AgentTV records the language a video is spoken in and its subtitle languages, where AI apps and search engines read them, and how answers handle a clip in another language.

Every video has a spoken language, and it can have subtitle tracks in other languages. AgentTV records both for every account and every source. AI apps and search engines read them, and answers use them to tell the asker what language a clip is in.

All language values are BCP 47 tags (the standard web language codes), for example `es`, `de-AT` or `en-US`. When AgentTV does not know a language, it leaves the field out. It never guesses from the title, the account or the country, and it never defaults to English.

## Spoken language

The spoken language is the language people speak in the video. AgentTV sets it from the first of these that exists:

1. **Owner.** A correction for one video. Tell us when a detected language is wrong, and we set it.
2. **Detected.** The transcription finds it in the audio.
3. **Feed.** Your [catalog feed](https://docs.agentcdn.com/guides/import-catalog.md#a-json-feed-instead-of-a-sitemap) declares it. This value holds only until a transcript exists.

`language_source` says which of the three set it (`owner`, `detected` or `feed`). `language_confidence` is the detection confidence from 0 to 1, and is set only for a detected language.

Transcripts, chapter quotes and moment text stay in the spoken language. AgentTV does not translate them.

## Subtitle tracks

A subtitle track is a file your source provides, such as a caption track your metadata API lists or an HLS subtitle rendition. Each track has a `language`, a `kind` (`human` or `auto`) and a `url`. Our own transcript is not a subtitle track.

`caption_languages` lists the languages of your `human` tracks. This is the list answers and labels name.

A track URL appears in public output only when it is a WebVTT file (`.vtt`) at a public `https` address with no signed or expiring token, and only when your rights allow quoting the video's words. An HLS subtitle playlist (`.m3u8`) is a stream address, not a caption file, so it is never published. In every other case the track keeps its language and its `url` is `null`.

## The language fields

The same fields appear on the [page block](https://docs.agentcdn.com/guides/page-metadata.md) JSON and in the ARV record:

```json theme={null}
{
  "language_primary": "es",
  "language_source": "detected",
  "language_confidence": 0.97,
  "subtitle_tracks": [
    { "language": "en", "kind": "human", "url": "https://cdn.example.com/subs/final.en.vtt" }
  ],
  "caption_languages": ["en"]
}
```

Search results, moments and citations from the API and MCP carry the short form: `language_primary` and `caption_languages`.

## Where the language appears

| Surface | What it carries |
| - | - |
| JSON-LD `VideoObject` (watch page and page block) | `inLanguage`, `subtitleLanguage` and `caption` |
| Page block JSON | the language fields above |
| Page block `body_html` | a `lang` attribute on the transcript and chapter text |
| [ARV record](https://docs.agentcdn.com/concepts/arv-record.md) | the asset `language` and `caption_languages`, plus the full fields as an extension |
| Search, moments and citations (API and MCP) | `language_primary` and `caption_languages` |
| JSON Feed (`feed.json`) | the item `language` |
| `llms.txt` and the watch page Markdown | the spoken language and the subtitle languages |

### JSON-LD

The page block and the watch page follow Google's VideoObject guidance and schema.org:

```json theme={null}
{
  "@type": "VideoObject",
  "inLanguage": "es",
  "subtitleLanguage": ["en", "de"],
  "caption": [
    { "@type": "MediaObject", "inLanguage": "en", "encodingFormat": "text/vtt", "contentUrl": "https://cdn.example.com/subs/final.en.vtt" },
    { "@type": "MediaObject", "inLanguage": "de", "encodingFormat": "text/vtt", "contentUrl": "https://cdn.example.com/subs/final.de.vtt" }
  ]
}
```

`Clip` items under `hasPart` inherit the language from the `VideoObject`, so they do not repeat it. The same rights rules apply as to the rest of the markup: a video that may not be cited gets no markup at all.

### ARV

The ARV 1.0 asset states the spoken language as `language` and the human subtitle languages as `caption_languages`. The full language fields use the standard's extension mechanism, under the `com.agentcdn` key:

```json theme={null}
{
  "extensions": {
    "com.agentcdn": {
      "video_language": {
        "language_primary": "es",
        "language_source": "detected",
        "language_confidence": 0.97,
        "subtitle_tracks": [
          { "language": "en", "kind": "human", "url": "https://cdn.example.com/subs/final.en.vtt" }
        ],
        "caption_languages": ["en"]
      }
    }
  }
}
```

ARV 1.0 has no moment language field, so each moment carries `extensions["com.agentcdn"].language_primary` and `caption_languages`, inherited from its video.

## Answers in the asker's language

Ask and the AI app tools answer in the language of the question, whatever language the videos are spoken in. The answer plan states that language as `answer_plan.language`.

When a cited clip is spoken in another language, the answer says so once. It names subtitles in the asker's language only when the video has a human track in that language. For example: "This clip is in Spanish, with English subtitles." A clip in the asker's language, or in no known language, is never named for its language.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.