Configuration

koto is configured with a koto.config.ts (or koto.config.js) file in your project root. Use the defineConfig() helper for full type safety and autocompletion.

Basic configuration

/** @type {import('koto').KotoConfig} */

export default {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'de', 'ja'],
  files: ['src/locales/[locale].json'],
  provider: {
    name: 'openai',
    model: 'gpt-4o-mini',
  },
})

Full config schema

`sourceLocale`

Type: string Required

The BCP 47 locale code for your source language.

sourceLocale: 'en'

`targetLocales`

Type: string[] Required

Array of BCP 47 locale codes to translate into.

targetLocales: ['es', 'fr', 'de', 'ja', 'ko', 'zh', 'pt-BR']

`files`

Type: string | string[] Required

Glob pattern(s) pointing to your locale files. Use [locale] as a placeholder for the locale code.

// Single pattern
files: 'src/locales/[locale].json'

// Multiple patterns
files: [
  'src/locales/[locale].json',
  'src/locales/[locale]/**/*.json',
]

`provider`

Type: ProviderConfig Required

The LLM provider to use for translations. See the Providers guide for full setup instructions.

provider: {
  name: 'openai',       // 'openai' | 'anthropic' | 'google' | 'ollama'
  model: 'gpt-4o-mini', // Model identifier
  baseUrl: undefined,    // Optional: custom API endpoint
}

`contexts`

Type: Record<string, ContextConfig> Default: undefined

Context profiles for tone-aware translations. See the Context Profiles guide for detailed usage.

contexts: {
  default: {
    tone: 'concise',
    instructions: 'UI strings. Keep translations short.',
  },
  marketing: {
    tone: 'persuasive and energetic',
    files: ['src/locales/marketing/[locale].json'],
  },
}

`typegen`

Type: { enabled?: boolean, outputPath?: string } Default: { enabled: false }

Configuration for TypeScript type generation. Run koto types to generate.

typegen: {
  enabled: true,
  outputPath: 'src/types/i18n.d.ts', // default: 'src/i18n.d.ts'
}

`quality`

Type: { enabled?: boolean, minScore?: number } Default: { enabled: true, minScore: 0.7 }

Quality scoring settings. Translations scoring below minScore trigger warnings. Use --fail-on-error in CI to block on quality issues.

quality: {
  enabled: true,
  minScore: 0.8, // 0-1 scale (0.8 = 80%)
}

`batch`

Type: { size?: number, concurrency?: number } Default: { size: 50, concurrency: 3 }

Controls how translation requests are batched and parallelized.

batch: {
  size: 30,        // keys per LLM request
  concurrency: 5,  // parallel requests
}

Framework examples

/** @type {import('koto').KotoConfig} */

export default {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'de', 'ja'],
  files: ['messages/[locale].json'],
  provider: {
    name: 'openai',
    model: 'gpt-4o-mini',
  },
  typegen: {
    outputPath: 'src/types/i18n.d.ts',

  },
};

/** @type {import('koto').KotoConfig} */

export default {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'de'],
  files: ['public/locales/[locale]/translation.json'],
  provider: {
    name: 'openai',
    model: 'gpt-4o-mini',
  },
  typegen: {
    outputPath: 'src/@types/i18next.d.ts',

  },
};

/** @type {import('koto').KotoConfig} */

export default {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'ja'],
  files: ['src/lang/[locale].json'],
  provider: {
    name: 'anthropic',
    model: 'claude-sonnet-4-20250514',
  },
  typegen: {
    outputPath: 'src/types/intl.d.ts',

  },
};

/** @type {import('koto').KotoConfig} */

export default {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr', 'de', 'ja', 'ko'],
  files: ['src/i18n/[locale].json'],
  provider: {
    name: 'google',
    model: 'gemini-2.0-flash',
  },
};

/** @type {import('koto').KotoConfig} */

export default {
  sourceLocale: 'en',
  targetLocales: ['es', 'fr'],
  files: ['locales/[locale].json'],
  provider: {
    name: 'ollama',
    model: 'llama3.2',
    baseUrl: 'http://localhost:11434',
  },
};

Environment variables

Provider API keys are read from environment variables. You can also set them in a .env file (koto loads .env automatically).

Variable	Provider
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic
`GOOGLE_API_KEY`	Google Gemini