# glotfile conventions & guardrails

The mental model, and the rules that keep you from fighting the tool.

## Local-first and git-native

Everything lives in the repo and is meant to be committed. There is no server, no
database, no account. The state file IS the database. A change isn't done until it's
saved to the state file, exported, and committed.

## The state file is the source of truth — exports are derived

- **Never hand-edit exported locale files** (ARB, PHP, JSON, `.po`, `.strings`,
  `.stringsdict`, XLIFF, YAML). They are regenerated by `glotfile export` and your edit
  will be overwritten. Edit the state file instead, then export.
- When you see a stale or wrong translation in an exported file, fix it in
  `keys.<name>.values.<locale>` and re-export.

## Keep diffs minimal

- Glotfile serializes deterministically (stable key order, fixed indent, trailing
  newline). Don't reformat the state file or reorder keys — let glotfile / the UI write
  it so diffs stay reviewable.
- Commit the state file and the regenerated outputs together, so the catalog and the
  locale files never drift apart in history. `glotfile check` verifies they're in sync.

## Two on-disk layouts — support both

A project is either single-file (`glotfile.json`) or split (`glotfile/` directory).
`glotfile` auto-detects (split wins). Read whichever exists; don't convert between them
unless asked (`glotfile split` does the conversion). Large catalogs prefer split for
smaller diffs.

## Config round-trip

Saving Settings from the UI replaces the entire `config` object. If you add a new
`config.*` field, it must be modeled in the Settings round-trip or it gets silently wiped
on the next save. When in doubt, set config via the UI/CLI rather than hand-editing.

## Secrets stay out of the committed config

AI provider API keys and editor choices live in **per-machine local settings**, never in
`glotfile.json`. Don't move them into the committed config and don't commit keys. A fresh
clone won't have them — a failed `translate` due to a missing key is a user setup step.

## Don't assume — read

Locales, output adapters, key-naming convention, and provider are all project-specific.
Read them from the state file and follow the existing patterns rather than introducing
new ones. Add a locale or output only when explicitly asked.
