---
title: "Introduction"
description: "Learn what diglot is, which problem it solves and how its pieces fit together."
canonical_url: "https://diglot.sh/guide/start/introduction"
---
# Introduction

> Learn what diglot is, which problem it solves and how its pieces fit together.

diglot translates markdown documentation one small unit at a time. Instead of keeping a translated copy of every file and hoping it stays in sync, it splits each document into segments, gives every segment an identity, and stores each translation as a small record in git.

## The problem

A translated documentation file starts to go stale on the day it is written. Someone fixes a typo in the source, rewords a paragraph or adds a section, and the translation either gets re-translated as a whole or drifts out of date. Reviewers cannot tell which part of a long file changed, and a machine that re-translates a page throws away the corrections people already made.

diglot avoids this by working below the level of the file:

1. It splits markdown documents into segments and gives each one a hash.
2. It stores translations in git, with one record per locale and hash.
3. It translates identical text only once, however many files, sources or branches contain it.
4. It skips re-translation when only URLs, components or HTML change, because those are not part of what a translator sees.

## Who writes the translation

diglot is built for human-first translation. A machine can write the first draft for a locale, but every draft is a record that people can edit, verify or reject, and the Action never overwrites a record that already exists. The [review states](https://diglot.sh/guide/concepts/review-and-status) describe what each of these decisions means for readers.

Machine translation is optional and is switched on per locale. Without it, diglot still extracts segments, tracks changes, validates records and builds bundles, so you can use it purely as the bookkeeping layer for a team of human translators.

## How the pieces fit

You keep your translations in a dedicated *translations repository*. It contains a `diglot.config.ts`, a `sources.yml` that points at the repositories whose documentation you translate, and one directory per locale. The sources themselves stay where they are.

The packages split the work along the same lines:

- A parser adapter ([comark](https://diglot.sh/adapters/comark) or [mdast](https://diglot.sh/adapters/mdast)) turns a document into segments and applies translations back to it.
- [`@diglot/core`](https://diglot.sh/core/overview) defines what a segment, a hash and a record are, and validates translations.
- [`@diglot/store`](https://diglot.sh/store/overview) reads and writes the files in the translations repository.
- [`@diglot/cli`](https://diglot.sh/workflow/cli/overview) and [`@diglot/action`](https://diglot.sh/workflow/action/overview) run the workflow: extract, diff, translate, validate and build.
- [`@diglot/mt`](https://diglot.sh/machine-translation/overview) drafts translations with a language model and checks them without one.

The result of a run is a bundle per locale, `dist/<locale>.json`, which your documentation site reads when it renders a page. [Use translations in your site](https://diglot.sh/guide/how-to/use-translations) explains that last step.

## Requirements

The command line tool, the Action and the store need Node.js 22.18 or later. The core, the adapters and `@diglot/mt` need Node.js 22 or later, and the core itself imports no Node built-ins, so it also runs in browsers and edge runtimes.

## Next steps

- Follow the [quick start](https://diglot.sh/guide/start/quick-start) to extract a first source and see its translation status.
- Read about [segments](https://diglot.sh/guide/concepts/segments) to understand what diglot treats as one unit.


## Sitemap

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