---
name: glotfile
description: Manage translations in a repo that uses glotfile (a local-first, git-native translation catalog). Use when working in a project containing a glotfile.json or glotfile/ directory, or when the user asks to add/edit/translate/export strings, work with locales/i18n, or run any `glotfile` command. Covers the CLI workflows, the glotfile.json schema, adding and editing strings, glossary, and project conventions.
---

# Managing glotfile

Glotfile keeps every translatable string for a project in one committed state file —
`glotfile.json` (or a `glotfile/` directory when storage is split). A local web UI,
a CLI, and pluggable AI providers all read and write that one file; platform locale
files (Flutter ARB, Laravel PHP, i18next/vue-i18n JSON, gettext `.po`, Apple
`.strings`/`.stringsdict`, Angular XLIFF, Rails YAML) are **generated from it on export**.

## The one rule that prevents most mistakes

**The state file is the single source of truth. Exported locale files are generated
output — never hand-edit them.** Editing `lib/l10n/app_fr.arb` or `resources/lang/fr/`
directly is wasted work: the next `glotfile export` overwrites it. Change the source
string in glotfile, then export.

To make a change:
1. Edit the **state file** (or run a `glotfile` command, or use the UI).
2. Run `glotfile export` to regenerate the locale files.
3. Commit both the state file and the regenerated outputs.

## Before you touch anything: discover the project's actual config

Do not assume the locales, providers, or output formats — read them. They live in the
state file's `config` block.

- Single-file layout: read `glotfile.json` → `.config`.
- Split layout: read `glotfile/config.json` → `.config`.

`config.sourceLocale`, `config.locales`, and `config.outputs[]` tell you what languages
exist and where exports land. Match the project; don't introduce a new locale or adapter
unless asked.

## Task → tool map

| You want to… | Do this |
| --- | --- |
| Add a new string | Add a `KeyEntry` to `keys` (source-locale value, `state: "source"`), then `glotfile translate` + `glotfile export`. See `references/workflows.md`. |
| Edit an existing source string | Change the source-locale value; downstream translations become stale — re-translate. See `references/workflows.md`. |
| Translate missing strings | `glotfile translate` (only fills empties; `--all` re-translates everything). |
| Write locale files | `glotfile export` |
| Find problems | `glotfile lint` (catalog issues) / `glotfile check` (lint + exports up to date) |
| Bootstrap from existing locale files | `glotfile import --format <adapter>` — see `references/workflows.md`. |
| Remove dead keys | `glotfile prune --unused` / `--empty-source` (dry-run unless `--write`). |
| Enforce term translations | Glossary — see `references/workflows.md`. |

## Reference files — read the one you need

- `references/cli-reference.md` — every command, its flags, and when to reach for it.
- `references/schema.md` — the shape of `glotfile.json`: `Config`, `KeyEntry`, plurals,
  placeholders, locale states. Read before editing the file by hand.
- `references/workflows.md` — step-by-step recipes: adding/editing strings, onboarding a
  repo via `import`, populating the glossary, building context for better translations.
- `references/conventions.md` — guardrails and the mental model. Read this if you are
  unsure whether an action fights the tool.

## Provider/API keys

AI provider settings and API keys live in **per-machine local settings** (not the
committed config), so they are absent in fresh clones. If a `translate` or
`build-context` run fails for a missing key/provider, that is a configuration step for
the user — don't invent keys or commit them.
