---
title: "Update a translation"
description: "Carry over or minimally revise an existing translation when its source changes."
canonical_url: "https://diglot.sh/machine-translation/update-translation"
---
# Update a translation

> Carry over or minimally revise an existing translation when its source changes.

When a source sentence is edited, retranslating it from scratch throws away wording that a person may have polished. `updateTranslation` takes the previous translation and the new source, and changes only what the edit affects.

```ts
import { updateTranslation } from '@diglot/mt'

const result = await updateTranslation(
  previousRecord,
  { previousSource: previousRecord.source, nextSource: segment },
  { locale: 'fr', model, glossary, style },
)

if (result.status === 'ok')
  console.log(result.derived) // 'carry' or 'update'
```

The first argument is anything with the previous `text`, usually a record. `previousSource` is the skeleton the previous translation was made from, or an object with `skeleton` and `placeholders` for better alignment. `nextSource` is the new segment.

## Aligning placeholders

Placeholder ids are numbered by position, so adding a link at the start of a sentence renumbers the rest. The function aligns the placeholders of the old source with those of the new source by matching words and by the type and markdown of each placeholder, and renumbers the previous translation to fit.

## Carry or update

When the aligned skeletons are identical, for example when only the context salt changed, the previous translation is returned as `derived: 'carry'` without a model call, provided it is still valid for the new segment.

Otherwise the model receives a word difference in `[-removed-] {+added+}` notation, the new source and the previous translation, with the instruction to copy unchanged sentences character for character. Edits that only change case or punctuation go to the model too. The result is `derived: 'update'`, and `changedSentences` lists the sentences of the new text that aren't in the previous one. Typography rules apply only to those sentences.

The output goes through the same [QA checks](https://diglot.sh/machine-translation/qa-checks) as a fresh translation, with `qaRetries` extra attempts. If all attempts fail, the result is `{ status: 'rejected', output?, issues, usage }`.

## Rejected records

A record that a reviewer rejected isn't a basis for an update. Translate the new segment with [`translateSegments`](https://diglot.sh/machine-translation/translate-segments) instead. The Action does exactly that.

## Result

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

<tbody>
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        ok
      </code>
      
       or <code>
        rejected
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      The updated skeleton (<code>
        ok
      </code>
      
       only)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derived
      </code>
    </td>
    
    <td>
      <code>
        carry
      </code>
      
       or <code>
        update
      </code>
      
       (<code>
        ok
      </code>
      
       only)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        changedSentences
      </code>
    </td>
    
    <td>
      Sentences not in the previous translation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        issues
      </code>
    </td>
    
    <td>
      The QA issues. For a carry, only warnings.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mt
      </code>
    </td>
    
    <td>
      Model, prompt version and candidate, for an update
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage
      </code>
    </td>
    
    <td>
      Requests, tokens and cost
    </td>
  </tr>
</tbody>
</table>


## Sitemap

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