Configuration Reference

wuchale can be configured using wuchale.config.js at the root of your project. TypeScript support depends on your JS runtime, meaning wuchale can import wuchale.config.ts but it doesn’t do anything extra, which will work if your runtime supports directly importing/running TS files (Node.js 22+, Bun, Deno). Other formats for configuration are not supported. An example configuration looks like:

wuchale.config.js

// @ts-check
import { defineConfig } from "wuchale"
import { adapter as svelte } from "@wuchale/svelte"

export default defineConfig({
    locales: ['en', 'es'],
    adapters: {
        main: svelte({
            catalog: './src/locales/{locale}',
        }),
    }
})

The above configuration shows how to configure wuchale with the Svelte adapter. The adapter accepts a configuration object as an argument. The configuration for each adapter is discussed in the adapter’s documentation. The main configuration is discussed here.

locales

type: string[]

The locales the app should be available in, including the source locale(s). If the app includes some files written in another spoken language, those files should be handled by a separate adapter config and the sourceLocale can be specified there, which only applies to that adapter config.

The locales here must be valid BCP 47 tags. For example, en, en-US, eng, zh-Hans are valid, but en_US, cn-simplified are invalid. The validation is done using Intl.DisplayNames.

localesDir

type: string default: ./src/locales

The localesDir is a place where all files wuchale works on like loaders and proxies are created. See File structure.

fallback

type: Record<string, string> default: {}

If you want to explicitly set the fallback behavior you can provide from-to pairs and it will check them in that sequence before falling back to the source locale. Regional variants fall back to the base locale by default. See the Fallback guide.

adapters

type: Record<string, Adapter> default: {}

Adapters are what handle the project specific operations like extracting the messages from the code and transforming it. They have to be provided with their own keys. The keys are how you can separate different parts of the project into smaller pieces and refer to them. The key also has to be a valid keyword like locale keys.

hmr

type: boolean default: true

Enable HMR updates during development. You can disable this to avoid the small overhead of live translation updates and work solely with the source language. HMR is highly optimized: it updates only the affected components, preserving application state and avoiding full reloads.

ai

type: AI default: gemini()

type AIPassThruOpts = {
    batchSize: number
    parallel: number
    group: Record<string, string[][]>
}

type AI = AIPassThruOpts & {
    name: string
    translate: (messages: string, instruction: string) => Promise<string>
}

Here you can give your own AI interface for live translation. The batchSize decides the maximum messages to translate in a single request, over which another request will be used. And parallel decides the number of requests to make in parallel.

If you want multiple target locales to be translated in the same prompt, you can provide the list of the groups to group.

The translate function receives the messages in a stringified JSON format with empty places for the translated messages, along with the instruction that explains what to do like from which language to which language, the expected format, etc. And the expected format is a JSON of translations by locale for each locale.

The default is gemini() which you can import and provide options to customize like ai: gemini({...}). The options should conform to the following type:

type GeminiOpts = Partial<
    AIPassThruOpts & {
        apiKey: string
        model: string
        think: boolean
    }
>

You can provide your API key here in apiKey directly, or use the special value env (default) to use the GEMINI_API_KEY environment variable. If the environment variable is not set, Gemini will not be used, as if it was disabled. It can also be always disabled by setting this to null, in which case the environment variable will not be used even if it is set.

logLevel

type: 'error' | 'warn' | 'info' | 'verbose' default: info

You can set the log level above which messages will be shown in the console. If you set it to verbose, all messages will be shown. verbose enables showing all extracted messages.