---
title: "Repository layout"
description: "See which files a diglot translations repository contains and which of them you edit by hand."
canonical_url: "https://diglot.sh/guide/start/repository-layout"
---
# Repository layout

> See which files a diglot translations repository contains and which of them you edit by hand.

A translations repository holds configuration that you write, records that people and machines write, and state that diglot generates. Keeping them apart in your head makes it clear what belongs in review and what you can regenerate.

```text
diglot.config.ts
sources.yml                      repositories, refs and directories that feed the corpus
glossary.yml                     optional terminology shared by every locale (x18n shape)
<locale>/
  glossary.yml                   terminology for this locale
  style.yml                      style and typography rules
  locale.yml                     machine translation switch and review metrics
  segments/<hh>/<hash>.json      one record per locale and hash
.diglot/manifest/<source>.json   source segments per file, one entry per line
.diglot/policy.json              snapshot of the extraction policy
dist/<locale>.json               built bundle: { version, locale, records }
```

## Files you write

`diglot.config.ts` and `sources.yml` define what is translated and into which locales. The files inside a locale directory (`glossary.yml`, `style.yml` and `locale.yml`) steer translation for that locale. Each is optional, and the [glossary and style guide](https://diglot.sh/guide/how-to/glossary-and-style) explains them.

## Records

Every translation is a JSON file at `<locale>/segments/<hh>/<hash>.json`. These files are the product of the repository: reviewers read them in pull requests, and the Action writes them. Each one is serialised with a fixed key order and a trailing newline, so diffs stay small. See [translation records](https://diglot.sh/guide/concepts/translation-records) for the fields.

## Generated state

Everything under `.diglot/` and `dist/` is derived. The state directory holds more than the manifests:

<table>
<thead>
  <tr>
    <th>
      Path
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        .diglot/manifest/<source>.json
      </code>
    </td>
    
    <td>
      The segments of each file of a source at its last extraction
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .diglot/policy.json
      </code>
    </td>
    
    <td>
      A snapshot of the extraction policy, which servers restore to extract segments the same way
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .diglot/lineage.json
      </code>
    </td>
    
    <td>
      For each live hash, up to five earlier hashes it evolved from, written by the Action
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .diglot/rejected/<locale>.json
      </code>
    </td>
    
    <td>
      Segments whose machine translation failed QA, with the reasons, written by the Action
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .diglot/checkouts/<repo>
      </code>
    </td>
    
    <td>
      Bare repositories fetched for sources that have a <code>
        repo
      </code>
      
       and no <code>
        path
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .diglot/sources/<source>
      </code>
    </td>
    
    <td>
      Plain files exported by <code>
        diglot checkout
      </code>
    </td>
  </tr>
</tbody>
</table>

Commit the manifests, the policy snapshot, the lineage and the rejections. The next run compares against the manifests, the lineage and the rejections, and a server needs the policy snapshot to apply translations at runtime. The checkouts and exported sources are caches, so keep them out of git. Change the locations with `stateDir` and `outDir` in the [configuration](https://diglot.sh/guide/how-to/configure).

## Bundles

`dist/<locale>.json` is what your documentation site reads. The [CLI](https://diglot.sh/workflow/cli/build) and the [Action](https://diglot.sh/workflow/action/inputs-and-outputs) write it, and you can turn it off in the Action with `build-dist: false` when you build bundles elsewhere.


## Sitemap

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