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.

.locallingo.yml

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.

ERB and secrets#

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

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