Getting started

Installation

To install wuchale, you have to install the base package and the adapter(s) you want to use. The adapter for vanilla JS/TS projects is built into the base package. For other projects, the adapter package has to be installed additionally.

This installation guide assumes that you have your source files under src. If not, you will have to configure the adapter and provide the files.

Install
Terminal window
npm install wuchale @wuchale/jsx @wuchale/vite-plugin
Terminal window
npm install wuchale @wuchale/svelte @wuchale/vite-plugin
Terminal window
npm install wuchale @wuchale/jsx @wuchale/vite-plugin
With Vite
Without Vite
Terminal window
npm install wuchale @wuchale/vite-plugin
Terminal window
npm install wuchale

Configure Vite

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { wuchale } from '@wuchale/vite-plugin'

export default defineConfig({
    plugins: [ wuchale(), react() ],
})

Svelte
SvelteKit

import { svelte } from '@sveltejs/vite-plugin-svelte'
import { wuchale } from '@wuchale/vite-plugin'

export default {
    plugins: [ wuchale(), svelte() ]
}

import { sveltekit } from '@sveltejs/kit/vite'
import { wuchale } from '@wuchale/vite-plugin'

export default {
    plugins: [ wuchale(), sveltekit() ]
}

import { defineConfig } from 'vite';
import solidPlugin from 'vite-plugin-solid';
import { wuchale } from '@wuchale/vite-plugin';

export default defineConfig({
    plugins: [wuchale(), solidPlugin()],
});

With Vite
Without Vite

import { wuchale } from '@wuchale/vite-plugin'

export default {
    plugins: [wuchale()]
}

Create Configuration

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

export default defineConfig({
    // sourceLocale is en by default
    otherLocales: ['es'],
    adapters: {
        main: jsx(),
    }
})

Svelte
SvelteKit

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

export default defineConfig({
    // sourceLocale is en by default
    otherLocales: ['es'],
    adapters: {
        main: svelte(),
    }
})

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

export default defineConfig({
    // sourceLocale is en by default
    otherLocales: ['es'],
    adapters: {
        main: svelte(),
        js: js({
            files: [
                'src/**/+{page,layout}.{js,ts}',
                'src/**/+{page,layout}.server.{js,ts}',
            ],
        })
    }
})

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

export default defineConfig({
    // sourceLocale is en by default
    otherLocales: ['es'],
    adapters: {
        main: jsx({
            variant: "solidjs"
        }),
    }
})

// @ts-check
import { adapter as basic } from 'wuchale/adapter-vanilla'
import { defineConfig } from 'wuchale'

export default defineConfig({
    // sourceLocale is en by default
    otherLocales: ['es'],
    adapters: {
        main: basic()
    }
})

Initialize locales
Terminal window
```
npx wuchale init
```
This command:
- Creates the locales directory if it doesn’t exist
- Creates the loader files, asking you which is correct
- Performs an initial extraction
Setup in Your App

Now that the loader files are created, you can edit them, export the things you need from there, and setup how the translations are loaded.
Look in the React setup guide
- Svelte: Look in the Svelte setup guide
- SvelteKit: Look in the SvelteKit setup guide
Look in the SolidJS setup guide
With Vite
Without Vite
import { loadLocale } from 'wuchale/load-utils' await loadLocale(locale)
No need

Start Coding!

Write your code components naturally. wuchale will extract and compile translations automatically:

function Hello() {
    return <p>Hello world</p>
}

<p>Hello world</p>

function Hello() {
    return <p>Hello world</p>
}

E.g. DOM

const showMsg = (element) => {
    element.innerHTML = 'Hello world'
}

For full usage examples, look inside the examples repository. It contains examples for different frameworks and usage patterns.

Workflow

wuchale’s workflow is inspired by Lingui. It follows similar steps but it does most of the steps automatically.

With Vite
Without Vite

You write your code
wuchale auto extracts the messages into the catalog files

During this step, if configured, Gemini does the automatic translation
The translator translates the messages by editing the extracted .po files
wuchale picks up the changes and updates the UI during dev
When you do the production build, wuchale auto compiles the catalogs and passes them to Vite to be included in the final build.

You write your code
You invoke the CLI command wuchale to extract the messages into the catalog files

During this step, if configured, Gemini does the automatic translation
The translator translates the messages by editing the extracted .po files
You invoke the CLI command wuchale again to compile the translated messages and write them to disk
When you run the app, everything works.