---
title: "Translate segments"
description: "Translate a list of segments page by page, and handle the ones that fail QA."
canonical_url: "https://diglot.sh/machine-translation/translate-segments"
---
# Translate segments

> Translate a list of segments page by page, and handle the ones that fail QA.

`translateSegments` takes segments and returns a translation for each one that passes the checks. It is the function the Action uses for segments that have no predecessor to update.

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

const { translations, rejected, usage } = await translateSegments(segments, {
  locale: 'fr',
  model,
  glossary, // loadGlossary(root, 'fr', { shared: config.glossary })
  style, // loadStyle(root, 'fr')
  subject: 'the documentation of Nuxt, a Vue web framework',
  context: file => ({ title: titles.get(file) }),
  batch: 'page',
  qaRetries: 1,
})

for (const t of translations)
  createRecord({ segment: byHash.get(t.hash)!, text: t.text, origin: 'mt', derived: t.derived, mt: t.mt })
```

Each segment needs a `hash`, `kind`, `format`, `skeleton` and `placeholders`, which a `Segment` from [`@diglot/core`](https://diglot.sh/core/segments) provides. The `context.file` of a segment decides which page it belongs to.

## How requests are formed

Segments are grouped by `context.file`, and each page is sent as one request so that the model sees the surrounding sentences. A page with more than `maxBatch` segments (40 by default) is split into evenly sized requests. With `batch: n`, requests carry at most `n` segments instead. Up to `concurrency` requests (4 by default) run at once.

Each request lists its segments with ids and the model answers with structured output matched by id. A segment whose id is missing from the answer counts as failed. The `context` option adds the page title and path to the prompt as read-only information. Pass an object, or a function that returns one for a segment's file.

Before sending, the function removes work that doesn't need a model:

- Segments with the same hash are translated once.
- Segments with no letters outside placeholders are skipped.
- Repeated atomic placeholders with the same markdown, such as two mentions of ``useFetch`` as `{0}` and `{2}`, are shown to the model as one id and restored in order afterwards.

Glossary entries go into the prompt only when their term occurs in the request.

## Checks and retries

Every output is trimmed, passes through the locale's typography rules, and is checked with [`runQa`](https://diglot.sh/machine-translation/qa-checks). A segment with an error-level issue is sent again with its problems listed, up to `qaRetries` times, and is then returned in `rejected` with its issues and its last output. Warnings don't block a translation. They come back in `translations[].issues`.

## Result

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

<tbody>
  <tr>
    <td>
      <code>
        translations
      </code>
    </td>
    
    <td>
      <code>
        { hash, text, derived: 'fresh', issues, mt }
      </code>
      
       for each accepted segment, in input order. <code>
        mt
      </code>
      
       is <code>
        { model, promptVersion, candidate }
      </code>
      
      , ready for a record.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rejected
      </code>
    </td>
    
    <td>
      <code>
        { hash, output?, issues }
      </code>
      
       for each segment that still failed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage
      </code>
    </td>
    
    <td>
      Requests, tokens and cost. See <a href="https://diglot.sh/machine-translation/usage-and-cost">
        usage and cost
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

Request failures other than an answer that doesn't match the schema are thrown, so a network or authentication error stops the call. Failed requests are retried twice by the AI SDK before that happens.

## Options

Besides the [shared options](https://diglot.sh/machine-translation/overview), `translateSegments` accepts `context`, `batch` (`page` by default), `maxBatch` (`40`) and `concurrency` (`4`).


## Sitemap

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