---
title: "Validation"
description: "Check a translated skeleton against the translation grammar of its source segment."
canonical_url: "https://diglot.sh/core/validation"
---
# Validation

> Check a translated skeleton against the translation grammar of its source segment.

`validate` decides whether a translation is safe to apply. Every record is validated when it is applied, when `diglot validate` runs, and after every machine translation.

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

validate('Nuxt est propulsé par {0}Nitro{/0}.', segment).ok // true
validate('Nuxt [Vite](https://example.com)', segment).errors // link syntax, missing placeholder
```

The second argument needs the segment's `kind`, `format` and `placeholders`, and optionally its `skeleton`. It returns `{ ok, errors, warnings }`, where each issue has a `code`, a `message` and sometimes an offset `at`. A warning is accepted but worth a reviewer's attention.

## Length

A translation that is valid markdown can still be wrong, for example when a model repeats a paragraph or cuts one short. Pass `options` as the third argument to check length too:

```ts
import { maxTranslationLength, validate } from '@diglot/core'

validate(translation, segment, { style, maxLength: maxTranslationLength(segment.skeleton) })
```

With a locale's `style`, a translation whose length ratio falls outside the style's `lengthRatio` band gets a `length` warning. The ratio counts characters outside placeholders, with whitespace collapsed, and is only checked for sources of 25 such characters or more. With `maxLength`, a longer translation gets a `too-long` error.

`lengthRatio(translation, source)` computes that ratio. `maxTranslationLength(source)` is a generous upper bound for any plausible translation: four times the source plus 100 characters, and at most 8000. It is the limit [`editRecord`](https://diglot.sh/core/review) applies by default.

## The rules

Markdown segments accept text, emphasis markers (`**`, `*`, `__`, `_`, `~~`) and the placeholders of their source. Anything that would parse as other markdown is an error, and literal punctuation must be escaped. Plain segments accept text and the source's placeholders, on one line, with no markup the source doesn't have. Code comments also reject comment terminators (`*/` and `-->`).

Headings, table cells, props, frontmatter values, navigation titles, code labels, code comments and image alts must be single-line.

## Issue codes

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Raised when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        empty
      </code>
    </td>
    
    <td>
      The translation is empty
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        multiline
      </code>
    </td>
    
    <td>
      A single-line kind contains a line break
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blank-line
      </code>
    </td>
    
    <td>
      A blank line would split the unit
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        block-syntax
      </code>
    </td>
    
    <td>
      A line starts with block syntax such as <code>
        #
      </code>
      
      , <code>
        >
      </code>
      
       or a list marker
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inline-code
      </code>
      
      , <code>
        link-syntax
      </code>
      
      , <code>
        html
      </code>
      
      , <code>
        binding
      </code>
      
      , <code>
        brace
      </code>
      
      , <code>
        component
      </code>
      
      , <code>
        table-pipe
      </code>
      
      , <code>
        entity
      </code>
      
      , <code>
        bare-url
      </code>
    </td>
    
    <td>
      An unescaped character would parse as code, a link, raw HTML, a binding or unknown brace syntax, an inline component, a table pipe in a table cell, an HTML entity or a URL that would autolink
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markup
      </code>
    </td>
    
    <td>
      A plain segment contains a backtick, emphasis marker, HTML tag, link or binding that its source doesn't have
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comment-terminator
      </code>
    </td>
    
    <td>
      A code comment contains <code>
        */
      </code>
      
       or <code>
        -->
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        missing-placeholder
      </code>
      
      , <code>
        duplicate-placeholder
      </code>
      
      , <code>
        unknown-placeholder
      </code>
      
      , <code>
        not-paired
      </code>
    </td>
    
    <td>
      A placeholder is absent, repeated, invented or used in the wrong form
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nesting
      </code>
      
      , <code>
        unclosed
      </code>
    </td>
    
    <td>
      Emphasis or paired placeholders aren't properly nested or closed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        too-long
      </code>
    </td>
    
    <td>
      The translation is longer than <code>
        maxLength
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        length
      </code>
    </td>
    
    <td>
      A warning: the length ratio is outside the style's band
    </td>
  </tr>
</tbody>
</table>

Repeating a code or binding placeholder is a warning, because some languages need to repeat a referent. Any other repeated placeholder is an error.

Applying also uses two codes of its own: `unaddressable` when an adapter can't locate a unit in the source, and `rejected` when a reviewer rejected the record.


## Sitemap

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