---
title: "Quick start"
description: "Set up a translations repository, extract a source and check its translation status."
canonical_url: "https://diglot.sh/guide/start/quick-start"
---
# Quick start

> Set up a translations repository, extract a source and check its translation status.

This walk-through creates a translations repository for one source and one locale, extracts the source into segments and builds a first bundle. You need Node.js 22.18 or later, git, and a local clone of the repository whose documentation you want to translate.

## Create the configuration

In an empty directory, create `diglot.config.ts`. It lists the locales you translate into, as BCP 47 tags such as `fr` or `pt-BR`.

```ts [diglot.config.ts]
import { defineConfig } from '@diglot/core'

export default defineConfig({
  locales: ['fr', 'ja'],
})
```

You don't need to install `@diglot/core` for this file. The `diglot` command resolves the import itself.

## Describe your sources

A source is a repository, a git ref and a directory inside it. Create `sources.yml` next to the config and point `path` at your local clone, relative to the config file.

```yaml [sources.yml]
sources:
  - name: nuxt-main
    repo: nuxt/nuxt
    ref: main
    path: ../nuxt
    dir: docs
```

Because `ref` is set, diglot reads the files at that ref through git, so uncommitted changes in your clone don't affect the result. If the directory at `path` doesn't exist yet, `pnpm dlx @diglot/cli checkout` fetches it for you from `repo`. The [sources guide](https://diglot.sh/guide/how-to/sources) covers every field.

## Extract the segments

Run `extract` to split every document of every source into segments:

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

The command prints one line per source with the number of files, segments and unique hashes, and writes the manifest to `.diglot/manifest/nuxt-main.json`. The manifest has one entry per segment, so commits show exactly which segments a source change touched.

## Check the status

`status` reports how much of each source is translated into each locale:

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

Nothing is translated yet, so every segment counts as `untranslated`. The same command shows later how many words are `machine`, `pending-review`, `edited`, `verified` or `rejected`.

## Validate and build

`validate` checks every record in the repository against its source segments, and `build` writes the bundle for each locale to `dist/<locale>.json`:

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

With no records, the bundles are empty. Records live at `<locale>/segments/<hh>/<hash>.json`, where `<hh>` is the first two characters of the hash.

## Add translations

You have two ways to fill the locales in:

- Write records yourself, or have translators do it. The [review guide](https://diglot.sh/guide/how-to/review-translations) shows the fields of a record.
- Let the [GitHub Action](https://diglot.sh/workflow/action/overview) draft them with a language model. Enable it per locale in `<locale>/locale.yml` and give it a model, as described in [Set up the Action](https://diglot.sh/workflow/action/setup).

## Next steps

- [Repository layout](https://diglot.sh/guide/start/repository-layout) lists every file diglot reads or writes.
- [Segments](https://diglot.sh/guide/concepts/segments) explains what `extract` produced.
- [Nuxt translations](https://diglot.sh/guide/examples/nuxt-translations) is a complete repository you can copy.


## Sitemap

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