---
title: "Records"
description: "Create, parse and classify translation records."
canonical_url: "https://diglot.sh/core/records"
---
# Records

> Create, parse and classify translation records.

The [fields of a record](https://diglot.sh/guide/concepts/translation-records) are defined by the `TranslationRecord` type. These functions create and check them.

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

<tbody>
  <tr>
    <td>
      <code>
        parseRecord(value)
      </code>
    </td>
    
    <td>
      Checks the shape of an unknown value and returns it as a record. Throws <code>
        RecordError
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createRecord({ segment, text, origin, ... })
      </code>
    </td>
    
    <td>
      Fills the identity fields (<code>
        hash
      </code>
      
      , <code>
        source
      </code>
      
      , <code>
        salt
      </code>
      
      ) from the segment and returns a normalised record
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        normaliseRecord(record)
      </code>
    </td>
    
    <td>
      Returns a copy with keys in <code>
        RECORD_KEYS
      </code>
      
       order and undefined fields dropped
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        recordStatus(record, segment?)
      </code>
    </td>
    
    <td>
      The status a reader sees
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        editRatio(record)
      </code>
    </td>
    
    <td>
      The share of the machine candidate that reviewers changed
    </td>
  </tr>
</tbody>
</table>

## Parsing

`parseRecord` rejects unknown keys, a hash that isn't 16 hexadecimal characters, empty required strings, unknown values of `origin`, `review` and `derived`, and a missing `prev` when `derived` isn't `fresh`. It requires `verifiedBy` when `review` is `verified`, and `rejectedBy` when it is `rejected` and only then. The error message starts with the record's hash when it has one.

## Creating

`createRecord` defaults `review` to `none`, `derived` to `fresh` (or `update` when `prev` is set) and `updatedAt` to now.

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

const record = createRecord({
  segment,
  text: 'Nuxt est propulsé par {0}Nitro{/0}.',
  origin: 'mt',
  mt: { model: 'anthropic/claude-sonnet-5.5', candidate: 'Nuxt est propulsé par {0}Nitro{/0}.' },
})
```

## Status

`recordStatus(record, segment?)` returns `untranslated`, `machine`, `pending-review`, `edited`, `verified` or `rejected`, following the rules in [review and status](https://diglot.sh/guide/concepts/review-and-status). When you pass a segment, the record's text is validated against it and a failure yields `rejected`.

## Edit ratio

`editRatio(record)` returns a number from 0 to 1, or `undefined` when the record has no `mt.candidate`. It is one minus the similarity between the candidate and the current text, so `0` means the reviewer changed nothing.

## Rejecting a translation

A rejected record has `review: 'rejected'` and `rejectedBy: { by, at }`. Readers then see the source text, and machine translation leaves it alone. An edit (`review: 'edited'` without `rejectedBy`) or a new source hash replaces the rejection. To make these changes from code, use the functions on the [review](https://diglot.sh/core/review) page, which check each transition for you.


## Sitemap

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