---
title: "Segments"
description: "Understand which parts of a markdown document diglot translates and how it classifies them."
canonical_url: "https://diglot.sh/guide/concepts/segments"
---
# Segments

> Understand which parts of a markdown document diglot translates and how it classifies them.

A segment is the smallest piece of a document that diglot translates on its own. When it reads a document, a parser adapter walks the content and turns every unit that carries prose into a segment, so a long page becomes a list of headings, paragraphs, list items and so on, in document order.

Working at this size is what lets diglot react to small edits. If you change one sentence in a page of fifty paragraphs, one segment changes and the other forty-nine keep their translations.

## What counts as a segment

Each segment has a kind that says where it came from:

<table>
<thead>
  <tr>
    <th>
      Kind
    </th>
    
    <th>
      Source
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        heading
      </code>
    </td>
    
    <td>
      A heading of any level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        paragraph
      </code>
    </td>
    
    <td>
      A paragraph outside any list, quote or component
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list-item
      </code>
    </td>
    
    <td>
      The text of a list item
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        table-cell
      </code>
    </td>
    
    <td>
      A table header or data cell
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockquote
      </code>
    </td>
    
    <td>
      The text of a blockquote
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        component-slot
      </code>
    </td>
    
    <td>
      Prose inside a component, such as a callout or a card body
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        html-block
      </code>
    </td>
    
    <td>
      Text inside HTML elements listed in the policy, such as <code>
        summary
      </code>
      
       or <code>
        figcaption
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        image-alt
      </code>
    </td>
    
    <td>
      The <code>
        alt
      </code>
      
       text of an image
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prop
      </code>
    </td>
    
    <td>
      A prose prop of a component, such as the <code>
        title
      </code>
      
       of a card
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        frontmatter
      </code>
    </td>
    
    <td>
      A prose value in frontmatter, such as <code>
        title
      </code>
      
       or <code>
        description
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        code-label
      </code>
    </td>
    
    <td>
      A code block label that reads as prose, such as <code>
        Directory Structure
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        code-comment
      </code>
    </td>
    
    <td>
      One line of prose in a code comment
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        navigation
      </code>
    </td>
    
    <td>
      A prose key of a <code>
        .navigation.yml
      </code>
      
       file
    </td>
  </tr>
</tbody>
</table>

Code blocks themselves, inline code, URLs and component names are never translated. They are protected as [placeholders](https://diglot.sh/guide/concepts/skeletons-and-hashes). A unit with no letters outside its placeholders has nothing to translate, so it carries zero words and is left alone.

## Markdown and plain segments

Segments come in two formats. A `markdown` segment may contain emphasis and links, while a `plain` segment is a single line of text with no markup. Props, frontmatter values, code labels, code comments and navigation titles are plain. A translator or a model may not add markdown to a plain segment, and the [validation rules](https://diglot.sh/core/validation) enforce that.

## The policy decides what is prose

Which props, containers and frontmatter paths carry prose depends on the components your documentation uses, so it is configurable. The default policy targets Nuxt UI and MDC documentation:

- Props: `title` on `read-more`, `video-accordion`; `title` and `description` on `card`; `label` on `u-button`; `name` on `collapsible`.
- Layout containers whose paragraphs stay plain paragraphs: `steps`, `card-group` and `code-group`.
- HTML elements whose text is translated: `summary`, `div`, `details`, `figcaption`, `dt` and `dd`.
- Frontmatter paths: `title`, `description`, `navigation.title`, `head.title`, `links[].label`, `seo.title` and `seo.description`.
- `.navigation.yml` keys: `title`, `titleTemplate` and `description`.
- Comments in fenced code blocks are extracted.

You override any of these with `policy` in the [configuration](https://diglot.sh/guide/how-to/configure), and [the policy reference](https://diglot.sh/core/policy-and-config) lists each field.

## Context

Every segment records where it came from: the file, the headings above it, its index in the file, the containers around it, and a detail such as the heading tag, the prop name or the code language. The context travels with the segment but is not part of its identity, so moving a paragraph under another heading doesn't change its hash. Each segment also records the lines it came from, which tools use to point a reviewer at the source.

## Next steps

- [Skeletons and hashes](https://diglot.sh/guide/concepts/skeletons-and-hashes) shows how a segment gets its identity.
- [Adapters](https://diglot.sh/adapters/overview) explains how comark and mdast differ.


## Sitemap

See the full [sitemap](https://diglot.sh/sitemap.md) for all pages.