# glotfile workflows

Recipes for the common jobs. All of them follow the same loop: **change the state file →
`glotfile export` → commit both.** Prefer the CLI/UI over hand-editing; edit by hand only
when no command fits (then match the deterministic format — see `references/schema.md`).

## Add a new string

1. Pick a key name that matches the project's existing convention (look at sibling keys —
   dotted `auth.login.title`, flat, etc.).
2. Add a `KeyEntry` to `keys` with the source-locale value and `state: "source"`:
   ```jsonc
   "cart.empty.title": {
     "context": "Heading on the empty-cart screen",
     "values": { "en": { "value": "Your cart is empty", "state": "source" } }
   }
   ```
   Add `context` when the string is ambiguous out of context — it measurably improves
   translation quality.
3. `glotfile translate` to fill the other locales (or `--key "cart.*"` to scope it).
4. `glotfile export` to write the locale files.
5. Wire the key up in the app code using the project's i18n accessor, then commit.

For a **plural** message, add a `plural: { "arg": "count" }` marker and use `forms`
instead of `value` (see `references/schema.md`). Use ICU placeholders like `{count}` and
keep them identical across locales — the lint placeholder rule enforces this.

## Edit an existing source string

1. Change the **source-locale** value in `keys.<name>.values.<sourceLocale>`.
2. Existing translations are now stale. Re-translate them: `glotfile translate --all
   --key "<name>"` (or let the user review). Glotfile tracks the source a translation was
   made from, so stale entries can be flagged `needs-review`.
3. `glotfile export`, then commit.

Never edit a translation in an exported file to "fix" it — fix it in the state file
(`state: "reviewed"` once a human approves) and re-export.

## Onboard a repo that already has locale files

1. Identify the existing format and pick the matching adapter (e.g. a Laravel app with
   `resources/lang/{locale}/` → `laravel-php`; a Flutter app with `app_{locale}.arb` →
   `flutter-arb`).
2. `glotfile import --format <adapter> --source <dir> --source-locale <code>` — this reads
   the existing files and writes a `glotfile.json`. Add `--cldr` if plurals use CLDR
   forms; `--force` to overwrite an existing state file.
3. Review the generated `config.outputs` so a subsequent `glotfile export` writes back to
   the same paths the project already uses.
4. `glotfile scan` then `glotfile build-context` (optional) to enrich keys with usage
   context before translating.

## Populate the glossary

The glossary constrains how particular terms are translated across the catalog; the lint
`glossary` rule flags violations. Each entry:

```jsonc
{
  "term": "Glotfile",
  "doNotTranslate": true,            // keep verbatim in every locale
  "caseSensitive": true,
  "notes": "Product name"
}
```

Or pin specific translations:

```jsonc
{
  "term": "cart",
  "translations": { "fr": "panier", "de": "Warenkorb" },
  "notes": "Use the e-commerce sense, not 'chariot'"
}
```

Add entries to the top-level `glossary` array. After adding them, `glotfile lint` will
flag existing translations that don't comply; `glotfile translate --all` re-translates
with the glossary applied.

## Improve translation quality with context

`glotfile scan` (index code references) → `glotfile build-context` (AI writes a short
`context` per key from how it's used in code) → `glotfile translate`. Keys with good
`context` translate far more accurately, especially short or ambiguous strings.
