---
title: "Glossary and style"
description: "Keep terminology and tone consistent by writing a shared glossary and a style file per locale."
canonical_url: "https://diglot.sh/guide/how-to/glossary-and-style"
---
# Glossary and style

> Keep terminology and tone consistent by writing a shared glossary and a style file per locale.

Machine translation is only as consistent as the instructions it gets. diglot gives you two places to write them down: a glossary for terms, and a style file for tone and typography. People also read both, so they work as a style guide for human translators.

## The shared glossary

A glossary shared by every locale uses [x18n](https://github.com/x18n-dev/x18n)'s `glossary` shape, so one file can serve your UI strings and your docs. Point `glossary` in the [configuration](https://diglot.sh/guide/how-to/configure) at it, or name it `glossary.yml` in the repository root and diglot finds it.

```yaml [glossary.yml]
- term: Nuxt
  doNotTranslate: true
- term: composable
  note: a Vue Composition API function
  translations:
    fr: composable
    ja: コンポーザブル
- term: hydration
  translations:
    fr: hydratation
```

An entry with `doNotTranslate: true` keeps the term in English. An entry whose translation for a locale equals the term also keeps it for that locale. An entry with a translation for the locale requires that translation, and an entry without one leaves the translation to the model, guided by `note`.

## Locale glossaries

x18n validates its configuration strictly, so options that only diglot understands can't go into the shared file. Put them in `<locale>/glossary.yml`, in diglot's own shape. An entry there replaces the shared entry with the same term.

```yaml [fr/glossary.yml]
terms:
  - term: layer
    match: \blayers?\b
    decision: keep-gloss
    gloss: couche
  - term: hydration
    match: \bhydrat(?:ion|es?|ed|ing)\b
    decision: translate
    target: hydratation
    accept: [hydrat]
```

Each entry has a `decision`:

- `keep` leaves the term in English.
- `keep-gloss` keeps the term and, on its first use in a page, adds the gloss in parentheses, as in `layer (couche)`.
- `translate` with a `target` requires that wording, and `accept` lists regular expressions that also count as following the entry. Without a `target`, the model translates according to `note`.

A term matches as a whole word and ignores case. Set `match` to a regular expression source to control matching, and `caseSensitive: true` to respect case. A `style` list in the same file adds free-form rules to the prompts.

## Style rules

`<locale>/style.yml` holds the rules a translator should follow and the typography to apply afterwards:

```yaml [fr/style.yml]
rules:
  - Address the reader as "vous".
  - Use sentence case in headings.
typography:
  spaceBefore: ';:!?»'
  spaceAfter: «
lengthRatio: [0.85, 1.7]
```

`rules` go into the prompt. `typography` is applied to machine output after translation, inserting a narrow no-break space (U+202F) before each `spaceBefore` character and after each `spaceAfter` character. `lengthRatio` overrides the range of translated to source length that the QA considers normal.

## Next steps

- [Glossary and style in the prompts](https://diglot.sh/machine-translation/glossary-and-style) shows how entries reach the model and which QA checks enforce them.


## Sitemap

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