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 has to be installed. Currently, only the Svelte adapter is available.

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.

1. Install

   Svelte

   npm install wuchale @wuchale/svelte @wuchale/vite-plugin

   Vanilla
   With Vite

   npm install wuchale @wuchale/vite-plugin

   Without Vite

   npm install wuchale

2. Configure Vite

   Svelte

   vite.config.js

   import { svelte } from '@sveltejs/vite-plugin-svelte'
   import { wuchale } from '@wuchale/vite-plugin'
   
   export default {
       plugins: [
           wuchale(),
           svelte(),
       ]
   }

   Vanilla
   With Vite

   vite.config.js

   import { wuchale } from '@wuchale/vite-plugin'
   
   export default {
       plugins: [wuchale()]
   }

   Without Vite

   No need

3. Create Configuration

   Svelte

   wuchale.config.js

   // @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(),
       }
   })

   Vanilla

   wuchale.config.js

   // @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()
       }
   })

4. Initialize locales

   npx wuchale init

   This command:

   • Creates the locales directory if it doesn’t exist
   • Creates the loader file if it doesn’t exist, asking you which is correct
   • Performs an initial extraction

5. Setup in Your App

   Now that the loader file is created, you can edit it, export the things you need from there, and setup how the translations are loaded.

   Svelte
   Svelte

   src/App.svelte

   <script>
       import { loadLocale } from 'wuchale/run-client'
   
       let locale = $state('en')
   </script>
   
   {#await loadLocale(locale)}
       <!-- @wc-ignore -->
       Loading translations...
   {:then}
       <!-- Your app content -->
   {/await}

   SvelteKit

   Assuming the use of a search parameter for the locale state: ?locale=en. But you can use anything else.

   src/routes/+layout.js

   import { locales } from 'virtual:wuchale/locales'
   import { loadCatalogs } from 'wuchale/run-client'
   import { loadIDs, loadCatalog } from '../locales/loader.svelte.js'
   
   /** @type import('./$types').LayoutLoad */
   export async function load({url}) {
       const locale = url.searchParams.get('locale') ?? 'en'
       if (!(locale in locales)) {
           return
       }
       return {
           locale,
           catalogs: await loadCatalogs(locale, loadIDs, loadCatalog)
       }
   }

   Vanilla
   With Vite

   import { loadLocale } from 'wuchale/run-client'
   await loadLocale(locale)

   Without Vite

   No need

6. Start Coding!

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

   Svelte

   <p>Hello world</p>

   Vanilla
   With Vite

   E.g. DOM

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

   Without Vite

   E.g. Server

   import { runWithLocale } from 'wuchale/run-server'
   //...
   app.get('/:locale', (req, res) => {
       runWithLocale(req.params.locale, () => res.send('Hello world'))
   })

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

Workflow

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

With Vite

1. You write your code

2. wuchale auto extracts the messages into the catalog files

   During this step, if configured, Gemini does the automatic translation

3. The translator translates the messages by editing the extracted .po files

4. wuchale picks up the changes and updates the UI during dev

5. When you do the production build, wuchale auto compiles the catalogs and passes them to Vite to be included in the final build.

Without Vite

1. You write your code

2. You invoke the CLI command wuchale to extract the messages into the catalog files

   During this step, if configured, Gemini does the automatic translation

3. The translator translates the messages by editing the extracted .po files

4. You invoke the CLI command wuchale again to compile the translated messages and write them to disk

5. When you run the app, everything works.

Learn about how it works.

What gets extracted

There are three possible places for a message to be in:

• Markup: inside HTML tags like <p>text</p>
• Attribute: insite element attributes like <span title="Text"></span>
• Script: strings inside JavaScript code

Inside of these, which messages exactly are extracted is decided by the adapter in use, because not all text should be extracted as a message. Some attributes and strings are not meant to be seen by the user.

The adapter uses a configurable heuristic function to make these decisions. This function receives the message along with other details and can decide whether to extract it or not.