---
title: "Apply"
description: "Resolve translations for segments and observe what happened to each one."
canonical_url: "https://diglot.sh/core/apply"
---
# Apply

> Resolve translations for segments and observe what happened to each one.

Adapters apply translations to documents, and the core supplies the pieces they share: looking up a translation, validating it, putting the protected spans back, and reporting what happened.

## Translations

A `Translations` value is a `Map` from hash to a translated skeleton or a `TranslationRecord`, or a function that returns one for a segment. A bare skeleton is accepted, so you can apply plain strings as well as full records.

## Resolving

`resolveTranslation(segment, translations)` returns one of:

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

<tbody>
  <tr>
    <td>
      <code>
        missing
      </code>
    </td>
    
    <td>
      There is no translation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rejected
      </code>
    </td>
    
    <td>
      A reviewer rejected the record (error code <code>
        rejected
      </code>
      
      ) or the text failed <a href="https://diglot.sh/core/validation">
        validation
      </a>
      
      . <code>
        errors
      </code>
      
       says why
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ok
      </code>
    </td>
    
    <td>
      <code>
        skeleton
      </code>
      
       is the validated translation, <code>
        text
      </code>
      
       has the current source's protected spans put back, and <code>
        warnings
      </code>
      
       lists warnings
    </td>
  </tr>
</tbody>
</table>

Rejected and missing segments keep their source text in the output. The `text` of an `ok` resolution always comes from the current source's placeholders, which is why a translated page links where the source links today.

## Reports

`createReport()` makes an empty report, and `tally(report, segment, resolution)` counts a resolution. The finished `ApplyReport` has `applied`, `missing` and `rejected`, where `rejected` lists `{ hash, file, index, errors }` for each segment.

## Apply events

The adapters' `apply` functions accept `onSegment`, called with an `ApplySegmentEvent` for each segment in extraction order:

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

<tbody>
  <tr>
    <td>
      <code>
        segment
      </code>
    </td>
    
    <td>
      The source segment, with its <code>
        hash
      </code>
      
       and <code>
        words
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        outcome
      </code>
    </td>
    
    <td>
      <code>
        translated
      </code>
      
      , <code>
        missing
      </code>
      
      , <code>
        rejected
      </code>
      
       or <code>
        skipped
      </code>
      
      . <code>
        skipped
      </code>
      
       means no translation and nothing to translate
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        errors
      </code>
    </td>
    
    <td>
      Why a <code>
        rejected
      </code>
      
       translation wasn't applied. Empty otherwise
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        record
      </code>
    </td>
    
    <td>
      The record the lookup returned, if any
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      What a reader sees, as from <code>
        recordStatus
      </code>
      
      . A translation given as a bare skeleton has no status
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        target
      </code>
    </td>
    
    <td>
      For block-level segments, a handle whose <code>
        setAttribute(name, value)
      </code>
      
       sets an attribute on the output node. <code>
        null
      </code>
      
       for frontmatter, props, image alts, code labels and code comments
    </td>
  </tr>
</tbody>
</table>

Segments that aren't translated keep their source text.

`wordsByStatus(events)` sums the words of segments by status, which gives per-page coverage. `createSegmentEvent(segment, resolution, target)` builds an event for adapter authors.


## Sitemap

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