Documentation

Configuration

Every key in parlancekit.config.json, what it does, and where it can be set.

ParlanceKit reads parlancekit.config.json from the directory you run it in. Point it elsewhere with --config path/to/config.json — useful in monorepos where packages need different settings.

Precedence: a CLI flag always overrides the config file. The config file overrides built-in defaults. Some options are config-only and have no flag equivalent — those are marked below.

Files and languages

Key	Flag	Description
sourceFile	--input, -i	Path to the file you are translating from.
sourceLanguage	—	Language your source is written in. Auto-detected when omitted; set it to be explicit. Your source does not have to be English.
targetLanguages	--langs	Array of language codes. On the CLI, pass a comma-separated list.
targetPattern	--pattern, -p	Where each translation is written. Use {lang} as a placeholder for the language code.

{
  "sourceFile": "src/locales/en.json",
  "targetLanguages": ["es", "fr"],
  "targetPattern": "src/locales/{lang}.json"
}

Without a target pattern, output lands beside the source: en.json becomes en.es.json. For a single language you can also pass --output with an exact path.

String Catalogs (.xcstrings) are the exception. A catalog holds every language in one file, so ParlanceKit updates it in place rather than writing one file per language. targetPattern is ignored for this format.

Voice

Key	Flag	Default	Description
tone	--tone, -t	neutral	Personality of the translation. One of the eleven tones below.
formality	--formality	default	Address forms. One of: default, formal, informal.
context	—	—	A sentence or two about your app. Sent with every request so the model knows the domain.

Supported tones

neutral, friendly, formal, informal, professional, technical, confident, concise, empathetic, playful, authoritative.

Common alternatives are understood and mapped to the closest canonical tone: casual becomes informal, polite becomes formal, assertive and marketing become confident, serious becomes authoritative, cheerful becomes playful, and respectful becomes empathetic. Anything unrecognised falls back to neutral.

Tone and formality are separate. Tone sets voice and personality; formality decides whether the translation addresses the reader as tu or vous, du or Sie. Both offer 'formal' and 'informal' because they are independent controls.

Protecting terms

Key	Flag	Matches against	Effect
glossary	--glossary, -g	Exact value	Terms that must never be translated. Brand names, product names.
skipPatterns	--skip-keys	Key name	Glob patterns. Matching strings are never sent to the model.
preservePatterns	--preserve-values	String value	Glob patterns. Matching values are returned exactly as written.

{
  "glossary": ["ParlanceKit", "Focus Frame"],
  "skipPatterns": ["*.id", "*.key", "analytics.*"],
  "preservePatterns": ["v*.*.*", "SKU-*"]
}

Patterns use glob syntax: * matches any characters, ? matches one, and [abc] matches a character class. Skipped and preserved strings are not sent to the provider and are not billed.

Fitting your layout

German runs about 30% longer than English; Finnish longer still. Character limits tell the model to find a concise equivalent rather than a literal translation that breaks your button.

{
  "charLimits": {
    "*.button": "max:20",
    "*.title": "approx:50"
  },
  "overrides": {
    "onboarding.welcome_title": {
      "charLimit": "max:40",
      "context": "First thing a new user sees"
    }
  }
}

Use max:N for a hard target — translations exceeding it are reported back to you — or approx:N for soft guidance. Overrides apply to a single key and take precedence over pattern-based limits.

charLimits and overrides are config-only, with no CLI flag, and require Pro or higher. Requests carrying them on a lower plan are rejected.

Provider

Set provider to openai, anthropic, or gemini. Omit it to use your organization's default. Provider choice requires Starter or higher.

Full example

{
  "sourceFile": "src/locales/en.json",
  "sourceLanguage": "en",
  "targetLanguages": ["es", "fr", "de", "ja"],
  "targetPattern": "src/locales/{lang}.json",
  "provider": "openai",
  "tone": "friendly",
  "formality": "informal",
  "context": "A focus and habit-tracking app for iOS.",
  "glossary": ["Focus Frame", "ParlanceKit"],
  "skipPatterns": ["*.id", "*.analytics_key"],
  "preservePatterns": ["v*.*.*"],
  "charLimits": {
    "*.button": "max:20"
  },
  "overrides": {
    "paywall.headline": { "charLimit": "max:40" }
  }
}