---
title: "Segments"
description: "Turn parsed inline content into a segment with a skeleton, placeholders and a hash."
canonical_url: "https://diglot.sh/core/segments"
---
# Segments

> Turn parsed inline content into a segment with a skeleton, placeholders and a hash.

An adapter converts each translatable unit of a document into a `SegmentDraft`, and `buildSegment` turns the draft into a `Segment`. The core never sees parser nodes, only the small inline representation described below.

## The inline representation

The inline content of a draft is a list of nodes:

<table>
<thead>
  <tr>
    <th>
      Node
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      Literal text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strong
      </code>
      
      , <code>
        emphasis
      </code>
      
      , <code>
        delete
      </code>
    </td>
    
    <td>
      Emphasis with children
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        link
      </code>
    </td>
    
    <td>
      A link with children and the markdown around its text (<code>
        open
      </code>
      
       and <code>
        close
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        atomic
      </code>
    </td>
    
    <td>
      A protected span with its markdown <code>
        source
      </code>
      
       and a <code>
        kind
      </code>
      
      : <code>
        code
      </code>
      
      , <code>
        link
      </code>
      
      , <code>
        component
      </code>
      
      , <code>
        html
      </code>
      
      , <code>
        image
      </code>
      
      , <code>
        break
      </code>
      
      , <code>
        binding
      </code>
      
       or <code>
        other
      </code>
    </td>
  </tr>
</tbody>
</table>

Nodes may carry a `data` field that the core passes through untouched, so an adapter can map a placeholder back to its own node.

## Building a segment

```ts
import { buildSegment } from '@diglot/core'

const segment = buildSegment({
  kind: 'paragraph',
  content: [
    { type: 'text', value: 'Nuxt is powered by ' },
    { type: 'link', open: '[', close: '](https://nitro.build)', children: [{ type: 'text', value: 'Nitro' }] },
    { type: 'text', value: '.' },
  ],
  context: { headingTrail: [], containers: [] },
  position: { startLine: 1, endLine: 1, precision: 'node' },
}, { file: 'intro.md', index: 0 })

segment.skeleton // 'Nuxt is powered by {0}Nitro{/0}.'
segment.hash // sha256 of the skeleton, truncated to 16 hex characters
```

`buildSegment` returns `undefined` for a unit without content. `buildSegments(file, drafts, policy?)` builds a whole file and numbers the segments in order. Passing a policy lets its `salt` function add a [context salt](https://diglot.sh/guide/concepts/skeletons-and-hashes) to ambiguous segments.

`prepareSegment` takes the same arguments and returns `{ segment, nodes }`, where `nodes[id]` is the link or atomic node behind placeholder `id`. Adapters use it to rebuild a translated unit from the current source nodes. With `resolvedSources: false` in the options, for drafts whose protected spans carry no markdown, the segment's `text` equals its `skeleton` and its `sourceHash` equals its `hash`.

A draft with string content is plain by default, and one with inline nodes is markdown. Set `format` to override that. In plain format, text is not escaped and emphasis is flattened.

## The segment

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        hash
      </code>
    </td>
    
    <td>
      The SHA-256 of the skeleton, and of the salt when there is one, truncated to 16 hex characters
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sourceHash
      </code>
    </td>
    
    <td>
      The same hash computed over <code>
        text
      </code>
      
      , so it changes when protected spans change
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kind
      </code>
      
      , <code>
        format
      </code>
    </td>
    
    <td>
      See <a href="https://diglot.sh/guide/concepts/segments">
        segments
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skeleton
      </code>
    </td>
    
    <td>
      The placeholder form, the only thing a translator or model sees
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      The skeleton with the placeholders put back
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        placeholders
      </code>
    </td>
    
    <td>
      <code>
        { id, type, source, close?, name?, hidesText? }
      </code>
      
       for each placeholder
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        words
      </code>
    </td>
    
    <td>
      The number of words outside placeholders. <code>
        0
      </code>
      
       means there is nothing to translate
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        context
      </code>
    </td>
    
    <td>
      The file, heading trail, index, containers and detail
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        position
      </code>
    </td>
    
    <td>
      Start and end line, and whether they are exact (<code>
        node
      </code>
      
      ), those of the enclosing top-level block (<code>
        block
      </code>
      
      ) or unknown (<code>
        file
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        salt
      </code>
    </td>
    
    <td>
      The context salt, when set
    </td>
  </tr>
</tbody>
</table>

## Skeleton helpers

<table>
<thead>
  <tr>
    <th>
      Function
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        hashSkeleton(skeleton, salt?, format?)
      </code>
    </td>
    
    <td>
      The identity hash of a skeleton
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        toSkeleton(nodes, format?)
      </code>
    </td>
    
    <td>
      The skeleton, placeholders and the node behind each placeholder
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fromSkeleton(skeleton, placeholders)
      </code>
    </td>
    
    <td>
      Puts protected spans back into a possibly translated skeleton
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseSkeleton(skeleton, placeholders, format?)
      </code>
    </td>
    
    <td>
      Parses a validated skeleton into text, emphasis and placeholder nodes, resolving escapes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        normalise(nodes)
      </code>
    </td>
    
    <td>
      Collapses whitespace and trims, so re-wrapping lines doesn't change the skeleton
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        escapeText(value)
      </code>
    </td>
    
    <td>
      Backslash-escapes characters that markdown or MDC would interpret
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        countWords
      </code>
      
      , <code>
        isPlaceholderOnly
      </code>
      
      , <code>
        plainText
      </code>
      
      , <code>
        toMarkdown
      </code>
    </td>
    
    <td>
      Small helpers on skeletons and nodes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pseudoTranslate(skeleton, format?)
      </code>
    </td>
    
    <td>
      A valid pseudo-translation: text runs are wrapped in <code>
        ⟦ ⟧
      </code>
      
       and their vowels accented
    </td>
  </tr>
</tbody>
</table>

`pseudoTranslate` is useful to see in a rendered page which text is translatable and which is not, since placeholders, emphasis markers and escapes are kept.


## Sitemap

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