---
title: "Use translations in your site"
description: "Read a locale bundle and apply it to documents with an adapter when you render your site."
canonical_url: "https://diglot.sh/guide/how-to/use-translations"
---
# Use translations in your site

> Read a locale bundle and apply it to documents with an adapter when you render your site.

Records are the source of truth, but your site shouldn't read thousands of small files. `diglot build` collects the records of a locale into one bundle, and an adapter applies that bundle to a document when you render it.

## Build the bundles

```bash
pnpm dlx @diglot/cli build
```

This writes `dist/<locale>.json`, containing `{ version, locale, records }` with records keyed by hash. Only records that a source still uses are included, and the output reports how many were skipped as unused. Pass `--all` to include every record. The [Action](https://diglot.sh/workflow/action/overview) builds the same bundles at the end of a run.

## Apply a bundle

Parse the bundle with `parseBundle` from [`@diglot/store`](https://diglot.sh/store/records-and-bundles), which validates every record and returns a `Map` keyed by hash. Then give that map to the `apply` function of the adapter that matches your parser:

```ts
import { readFile } from 'node:fs/promises'
import { apply, parse, render } from '@diglot/comark'
import { parseBundle } from '@diglot/store'

const records = parseBundle(await readFile('dist/fr.json', 'utf8'))

const doc = await parse(markdown)
const { doc: translated, report } = await apply(doc, records)

const output = await render(translated)
```

`apply` extracts the document's segments, looks up each hash in the map, validates the translation against the current source and replaces the text. The report counts applied, missing and rejected segments. A segment without a usable translation keeps its source text, so a page is always complete, and the protected spans always come from the current source.

Use `parser: 'mdast'` in your configuration and `@diglot/mdast` when your sources are plain markdown. Its `apply` takes the markdown string and returns markdown. Apply the same [policy](https://diglot.sh/guide/concepts/segments) you configured for extraction, or the segments won't line up with the bundle.

## Serve the latest translations

A bundle is fixed at build time. To serve translations as soon as they are committed, read the translations repository from an archive on your server with [`@diglot/store/runtime`](https://diglot.sh/store/runtime), and restore the policy snapshot so that your segments hash the same way. Navigation titles and title templates that you build at runtime can be translated one value at a time with [`translateLabel`](https://diglot.sh/adapters/comark#labels).

## Mark untranslated text

Readers benefit from knowing which text isn't translated. Both adapters accept an `onSegment` callback that receives each segment's outcome and a handle to set an attribute on its block:

```ts
const { doc: translated } = await apply(doc, records, {
  onSegment(event) {
    if (event.outcome === 'missing' || event.outcome === 'rejected')
      event.target?.setAttribute('lang', 'en')
  },
})
```

The `lang` attribute lets screen readers pronounce the fallback text correctly and lets your CSS style it. `event.status` also tells you whether a translation is `machine`, `pending-review`, `edited` or `verified`, so you can flag drafts. See [apply events](https://diglot.sh/core/apply).

## Next steps

- [Adapters](https://diglot.sh/adapters/overview) compares comark and mdast.
- [Apply](https://diglot.sh/core/apply) describes outcomes, statuses and `wordsByStatus` for per-page coverage.


## Sitemap

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