Skip to content

Configuration ​

Interceptor loads interceptor.config.ts/js/cjs/mjs/json from the current directory or any parent directory.

Full example ​

ts
import type { InterceptorConfig } from "@wrkspace-co/interceptor";

const config: InterceptorConfig = {
  rootDir: ".",
  include: ["src/**/*.{ts,tsx,js,jsx,vue,svelte,astro}"],
  exclude: ["**/node_modules/**", "**/dist/**"],
  locales: ["en", "fr"],
  defaultLocale: "en",
  llm: {
    provider: "openai",
    model: "gpt-4o-mini",
    apiKeyEnv: "OPENAI_API_KEY"
  },
  i18n: {
    messagesPath: "src/locales/{locale}.json"
  },
  extractor: {
    functions: ["t"],
    taggedTemplates: [],
    reactIntl: {
      formatMessage: true,
      formattedMessage: true,
      defineMessages: true
    },
    i18next: {
      enabled: true,
      functions: ["t"],
      memberFunctions: ["t"],
      objects: ["i18n", "i18next"],
      useDefaultValue: true,
      keyAsDefault: true,
      transComponent: true
    },
    vueI18n: {
      enabled: true,
      functions: ["$t"],
      memberFunctions: ["t", "$t"],
      objects: ["i18n", "$i18n", "i18nGlobal", "i18nInstance", "this"],
      keyAsDefault: true
    }
  },
  batch: {
    size: 20,
    delayMs: 0,
    localeConcurrency: 2
  },
  watcher: {
    debounceMs: 200
  },
  cleanup: {
    removeUnused: false
  }
};

export default config;

Core options ​

Required:

  • locales: List of locale codes.
  • defaultLocale: Locale used as the source language.
  • llm.provider: LLM provider name.
  • llm.model: Model identifier for the chosen provider.

Optional:

  • rootDir: Base directory for resolving paths.
  • include: Glob patterns to scan.
  • exclude: Glob patterns to ignore.

Config reference ​

Top-level ​

FieldPurposeRequiredDefault
rootDirBase directory for resolving paths.No.
includeGlob patterns to scan.No["src/**/*.{js,jsx,ts,tsx,vue,svelte,astro}"]
excludeGlob patterns to ignore.No["**/node_modules/**", "**/dist/**", "**/build/**", "**/.next/**", "**/coverage/**"]
localesList of target locales.Yes—
defaultLocaleSource locale used for translation.Yes—
extractorExtraction behavior overrides.NoDefaults in "Extractor" table
i18nLocale file resolution settings.NoDefaults in "i18n" table
llmLLM provider and model settings.YesDefaults in "LLM" table
batchBatch sizing and concurrency.NoDefaults in "Batch" table
watcherWatch mode tuning.NoDefaults in "Watcher" table
cleanupRemove unused keys after extraction.NoDefaults in "Cleanup" table
budgetToken budget guardrails.NoDefaults in "Budget" table

LLM ​

FieldPurposeRequiredDefault
llm.providerPrimary LLM provider.Yes—
llm.modelPrimary model identifier.Yes—
llm.apiKeyEnvEnv var for provider API key.NoProvider default (see LLM Providers)
llm.baseUrlOverride API base URL.NoProvider default (OpenAI-compatible required)
llm.temperatureSampling temperature.No0.2
llm.fallbacksOrdered list of fallback providers.No[]
llm.fallbacks[].providerFallback provider.Yes (if fallbacks)—
llm.fallbacks[].modelFallback model.NoPrimary llm.model
llm.fallbacks[].apiKeyEnvFallback API key env var.NoProvider default
llm.fallbacks[].baseUrlFallback base URL override.NoProvider default
llm.fallbacks[].temperatureFallback temperature override.NoPrimary llm.temperature
llm.retriesRetry attempts per provider.No2
llm.retryDelayMsInitial retry delay.No500
llm.retryMaxDelayMsMax backoff delay.No4000

i18n ​

FieldPurposeRequiredDefault
i18n.provideri18n integration type.No"react-intl"
i18n.messagesPathLocale path template.No"src/locales/{locale}.json"
i18n.messagesDirBase locale directory.No"src/locales"
i18n.localeFilePatternLocale filename pattern.No"{locale}.json"
i18n.resolveMessagesFileCustom resolver function.No—

Extractor ​

FieldPurposeRequiredDefault
extractor.functionsGlobal translation functions.No["t"]
extractor.taggedTemplatesTagged template extractors.No[]
extractor.reactIntl.formatMessageExtract intl.formatMessage.Notrue
extractor.reactIntl.formattedMessageExtract <FormattedMessage />.Notrue
extractor.reactIntl.defineMessagesExtract defineMessages().Notrue
extractor.i18next.enabledEnable i18next extraction.Notrue
extractor.i18next.functionsi18next function names.No["t"]
extractor.i18next.memberFunctionsi18next member function names.No["t"]
extractor.i18next.objectsi18next object names.No["i18n", "i18next"]
extractor.i18next.useDefaultValueUse defaultValue as source.Notrue
extractor.i18next.keyAsDefaultUse key when no default.Notrue
extractor.i18next.transComponentExtract <Trans> content.Notrue
extractor.vueI18n.enabledEnable vue-i18n extraction.Notrue
extractor.vueI18n.functionsvue-i18n function names.No["$t"]
extractor.vueI18n.memberFunctionsvue-i18n member function names.No["t", "$t"]
extractor.vueI18n.objectsvue-i18n object names.No["i18n", "$i18n", "i18nGlobal", "i18nInstance", "this"]
extractor.vueI18n.keyAsDefaultUse key when no default.Notrue

Batch ​

FieldPurposeRequiredDefault
batch.sizeStrings per LLM request.No20
batch.delayMsDelay between batches.No0
batch.localeConcurrencyParallel locale translations.No2

Watcher ​

FieldPurposeRequiredDefault
watcher.debounceMsDebounce for file changes.No200

Cleanup ​

FieldPurposeRequiredDefault
cleanup.removeUnusedRemove keys not in source.Nofalse
cleanup.transientKeyWindowMsPrune recent auto-generated keys replaced by longer strings.No300000

Budget ​

FieldPurposeRequiredDefault
budget.maxTokensPerRunCap tokens per run.NoInfinity
budget.maxTokensPerLocaleCap tokens per locale.NoInfinity

i18n file locations ​

Use a template path with {locale}:

ts
i18n: {
  messagesPath: "src/locales/{locale}.json"
}

Or use a resolver:

ts
i18n: {
  resolveMessagesFile: (locale) => `src/i18n/${locale}/messages.json`
}

LLM configuration ​

ts
llm: {
  provider: "openai",
  model: "gpt-4o-mini",
  apiKeyEnv: "OPENAI_API_KEY",
  baseUrl: "https://api.example.com/v1",
  temperature: 0.2,
  fallbacks: [
    {
      provider: "anthropic",
      model: "claude-3-5-sonnet-20240620",
      apiKeyEnv: "ANTHROPIC_API_KEY"
    },
    {
      provider: "google",
      model: "gemini-1.5-pro",
      apiKeyEnv: "GEMINI_API_KEY"
    }
  ],
  retries: 2,
  retryDelayMs: 500,
  retryMaxDelayMs: 4000
}

Budget guardrails ​

Control maximum translation volume per run and per locale. Budgets are approximate and based on string length.

ts
budget: {
  maxTokensPerRun: 6000,
  maxTokensPerLocale: 2000
}

Extraction configuration ​

  • functions: Global function names like t.
  • taggedTemplates: Tagged templates like t`key` .
  • reactIntl: Enable react-intl extraction.
  • i18next: Enable i18next extraction and default value handling.
  • vueI18n: Enable vue-i18n extraction for scripts and templates.

Batch configuration ​

ts
batch: {
  size: 20,
  delayMs: 0,
  localeConcurrency: 2
}

localeConcurrency controls how many locales are translated in parallel.

Watcher configuration ​

ts
watcher: {
  debounceMs: 200
}

Cleanup unused keys ​

ts
cleanup: {
  removeUnused: true
}

Transient key pruning ​

When you save midway through typing, Interceptor can generate short, incomplete keys. cleanup.transientKeyWindowMs removes recently auto-generated keys that are no longer in source when a longer replacement key appears.