Configuration

# Configuration

Everything app-specific lives in .locallingo.yml — a defaults block plus optional per-package overrides.

## The file

.locallingo.yml at your app root.

locallingo reads a single YAML file, `.locallingo.yml` (or `.locallingo.yaml`), from your app root. It has a `defaults:` block that applies to the whole app and an optional `packages:` list for per-location overrides. With no config file at all, the shipped defaults are used.

## The defaults block

A representative config. Every key has a default, so you only set what differs from the shipped values — see the full list on the [Configuration reference](https://locallingo.zoolutions.llc/docs/configuration-reference).

```ruby
defaults:
  source_locale: en
  target_locales: [de, sv]

  locales_dir: config/locales
  state_dir: .i18n-state

  provider: openai
  translate:
    model: gpt-5-mini
    batch_size: 20
  quality:
    model: gpt-4o-mini
    british_spellings: false
    terminology: business

  context: "Acme, a business application"
  glossary:
    entity: "business/company account holder"
  language_guides:
    de:
      file: config/locales/.guides/de.md

  validators:
    missing: true
    outdated: true
    duplicate_values: true
    manual_edits: false

  strict:
    strict: [missing, outdated]
    strict_all: [missing, outdated, duplicate_value]

  after_translate:
    - "bundle exec i18n-tasks normalize -p"
```

## How values resolve

A resolved config is the shipped defaults, deep-merged with your `defaults:` block, deep-merged with the selected `packages:` entry (if you pass `--package`). "Deep-merged" means a package that overrides one `quality.model` keeps the sibling `quality.british_spellings` from the defaults — you never restate a whole sub-tree to change one key. See [Multiple packages](https://locallingo.zoolutions.llc/docs/packages).

## ERB and secrets

The file is ERB-evaluated, so `<%= ENV["SOMETHING"] %>` works for values you want to vary by environment.

> **Warning:** Never put raw API keys in `.locallingo.yml`. The LLM provider reads its own credentials from the environment via RubyLLM — locallingo never stores keys.