Skip to content
koto

Context Profiles

Context profiles let you assign different translation tones, terminology, and instructions to different parts of your application. Instead of treating all strings identically, koto adapts translations to match the intent of each section.

Why context matters

Consider the word “Submit” in two places:

  • On a payment form, it should translate as the formal equivalent of “Confirm Payment.”
  • On a feedback widget, it could translate as “Send” or “Share.”

Without context, a translation tool picks one and applies it everywhere. With context profiles, each usage gets the right translation.

Marketing pages

Energetic, persuasive tone. Short punchy copy. Brand-aware terminology.

Legal & compliance

Formal, precise language. Jurisdiction-appropriate legal terms. No ambiguity.

UI strings

Concise labels. Consistent with platform conventions (“Settings” not “Configuration”).

Support content

Friendly, helpful tone. Clear step-by-step instructions. Empathetic language.

Defining profiles

Profiles live in the contexts section of your koto.config.ts. Each profile specifies which files it applies to, the desired tone, and any additional instructions.

import { defineConfig } from 'koto'


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


  contexts: {
    // Applied to files not matched by any other context
    default: {
      tone: 'concise',
      instructions: 'UI strings. Keep translations short and consistent with platform conventions.',
    },


    marketing: {
      tone: 'persuasive and energetic',
      instructions: 'Keep translations punchy. Prefer short, impactful words.',
      files: ['src/locales/marketing/[locale].json'],
    },


    legal: {
      tone: 'formal and precise',
      instructions: 'Use jurisdiction-appropriate legal terminology. Avoid ambiguity.',
      glossary: './glossaries/legal.json',
      files: ['src/locales/legal/[locale].json'],
    },


    support: {
      tone: 'friendly and helpful',
      instructions: 'Use clear, simple language. Be empathetic. Avoid jargon.',
      files: ['src/locales/support/[locale].json'],
    },
  },
})

How resolution works

  1. File matching — When koto translates a file, it checks which profile’s files pattern matches the file path.

  2. Default fallback — If no profile matches, the default context is applied. If no default is defined, koto translates without additional context.

  3. Prompt assembly — koto builds an LLM prompt that includes the profile’s tone, instructions, and any glossary terms.

  4. Translation — The LLM translates with full awareness of the intended context, producing output that matches the desired tone and terminology.

Profile options

tone

Type: string

A natural language description of the desired tone, included in the LLM prompt.

tone: 'concise'
tone: 'formal and precise'
tone: 'persuasive and energetic'
tone: 'friendly, casual, and approachable'

instructions

Type: string

Additional guidance for the LLM — domain-specific rules, formatting constraints, or style notes.

instructions: 'UI strings. Keep translations under 30 characters where possible.'
instructions: 'Legal copy. Use formal register. Preserve all placeholder variables.'

files

Type: string | string[]

Glob pattern(s) that determine which files this profile applies to. Uses the same [locale] placeholder as the top-level files option.

files: ['src/locales/marketing/[locale].json']
files: ['src/locales/legal/[locale].json', 'src/locales/compliance/[locale].json']

glossary

Type: string

Path to a JSON glossary file. Terms are included in the LLM prompt to ensure consistent translation of domain-specific terminology.

glossary: './glossaries/legal.json'

Glossary files

A glossary maps source terms to expected translations per locale:

{
  "terms": {
    "Data Controller": {
      "es": "Responsable del tratamiento",
      "fr": "Responsable du traitement",
      "de": "Verantwortlicher",
      "ja": "データ管理者"
    },
    "Consent": {
      "es": "Consentimiento",
      "fr": "Consentement",
      "de": "Einwilligung",
      "ja": "同意"
    }
  }
}

When a glossary is attached to a profile, koto sends the relevant terms to the LLM as reference.

Translating a specific context

Translate only the files belonging to one profile:

Terminal window
# Legal content only
npx koto translate --context legal


# Marketing content only
npx koto translate --context marketing

Useful when you’ve updated only one section and want a fast, targeted run.

Best practices

  1. Start with default — Define a default context for general UI strings. It catches everything not matched by a specific profile.

  2. Be specific with tone — Instead of “formal,” write “formal and precise, suitable for legal documents.” The more specific, the better the LLM performs.

  3. Use glossaries for domain terms — Industry-specific terminology (legal, medical, financial) benefits from glossary files that enforce consistency.

  4. Organize files by context — Structure locale files so each profile maps to a clear directory:

    src/locales/
    ├── en.json              # default context
    ├── marketing/
    │   └── en.json          # marketing context
    ├── legal/
    │   └── en.json          # legal context
    └── support/
        └── en.json          # support context

  5. Keep profiles focused — Each should represent a distinct translation need. If two have the same tone and instructions, merge them.