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.

React

1. Install

   npm install wuchale @wuchale/jsx

2. Configure Vite

   vite.config.js

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

3. Create Configuration

   wuchale.config.js

   // @ts-check
   import { adapter as jsx } from "@wuchale/jsx"
   import { defineConfig } from "wuchale"
   
   export default defineConfig({
       locales: ['en', 'es'],
       adapters: {
           main: jsx({ loader: 'react' }),
       }
   })

4. Scaffold and initial extract

   npx wuchale

5. Setup in Your App

   Connect the locale selection and loading logic to your app. Follow the React setup guide.

6. Start Coding!

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

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

Svelte

1. Install

   npm install wuchale @wuchale/svelte

2. Configure Vite

   vite.config.js

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

3. Create Configuration

   wuchale.config.js

   // @ts-check
   import { adapter as svelte } from "@wuchale/svelte"
   import { defineConfig } from "wuchale"
   
   export default defineConfig({
       locales: ['en', 'es'],
       adapters: {
           main: svelte({ loader: 'svelte' }),
       }
   })

4. Scaffold and initial extract

   npx wuchale

5. Setup in Your App

   Connect the locale selection and loading logic to your app. Follow the Svelte setup guide.

6. Start Coding!

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

   <p>Hello world</p>

SvelteKit

1. Install

   npm install wuchale @wuchale/svelte

2. Configure Vite

   vite.config.js

   import { sveltekit } from '@sveltejs/kit/vite'
   import { wuchale } from 'wuchale/vite'
   
   export default {
       plugins: [ wuchale(), sveltekit() ]
   }

3. Create Configuration

   wuchale.config.js

   // @ts-check
   import { adapter as svelte } from "@wuchale/svelte"
   import { adapter as js } from 'wuchale/adapter-vanilla'
   import { defineConfig } from "wuchale"
   
   export default defineConfig({
       locales: ['en', 'es'],
       adapters: {
           main: svelte({ loader: 'sveltekit' }),
           js: js({
               loader: 'vite',
               files: [
                   'src/**/+{page,layout}.{js,ts}',
                   'src/**/+{page,layout}.server.{js,ts}',
               ],
           })
       }
   })

4. Scaffold and initial extract

   npx wuchale

5. Setup in Your App

   Connect the locale selection and loading logic to your app. Follow the SvelteKit setup guide.

6. Start Coding!

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

   <p>Hello world</p>

SolidJS

1. Install

   npm install wuchale @wuchale/jsx

2. Configure Vite

   vite.config.js

   import { defineConfig } from 'vite';
   import solidPlugin from 'vite-plugin-solid';
   import { wuchale } from 'wuchale/vite';
   
   export default defineConfig({
       plugins: [wuchale(), solidPlugin()],
   });

3. Create Configuration

   wuchale.config.js

   // @ts-check
   import { adapter as jsx } from "@wuchale/jsx"
   import { defineConfig } from "wuchale"
   
   export default defineConfig({
       locales: ['en', 'es'],
       adapters: {
           main: jsx({
               loader: 'solidjs',
               variant: 'solidjs',
           }),
       }
   })

4. Scaffold and initial extract

   npx wuchale

5. Setup in Your App

   Connect the locale selection and loading logic to your app. Follow the SolidJS setup guide.

6. Start Coding!

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

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

Astro

1. Install

   npm install wuchale @wuchale/astro

2. Configure Vite

   astro.config.js

   import { wuchale } from 'wuchale/vite';
   import { defineConfig } from 'astro/config';
   
   // https://astro.build/config
   export default defineConfig({
       vite: {
           plugins: [wuchale()],
       },
       i18n: {
           locales: ['en', 'es'],
           defaultLocale: 'en',
           routing: {
               prefixDefaultLocale: true,
           }
       },
   });

   Note

   Additionally, since we will use path prefixes using Astro’s i18n routing, everything inside src/pages has to be moved to src/[locale]/pages and imports have to be adjusted accordingly.

3. Create Configuration

   wuchale.config.js

   // @ts-check
   import { adapter as astro } from "@wuchale/astro"
   import { defineConfig } from "wuchale"
   
   export default defineConfig({
       locales: ['en', 'es'],
       adapters: {
           main: astro(),
       }
   })

4. Scaffold and initial extract

   npx wuchale

5. Setup in Your App

   Connect the locale selection and loading logic to your app. Follow the Astro setup guide.

6. Start Coding!

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

   <p>Hello world</p>

Vanilla

1. Install

   npm install wuchale

2. Configure Vite (only if using Vite)

   vite.config.js

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

3. Create Configuration

   wuchale.config.js

   // @ts-check
   import { adapter as basic } from 'wuchale/adapter-vanilla'
   import { defineConfig } from 'wuchale'
   
   export default defineConfig({
       locales: ['en', 'es'],
       adapters: {
           main: basic({
               loader: 'vite' // If using Vite. Otherwise 'default'
           })
       }
   })

4. Scaffold and initial extract

   npx wuchale

5. Setup in Your App (if using Vite)

   Connect the locale selection and loading logic to your app.

   import { loadLocale } from 'wuchale/load-utils'
   await loadLocale(locale)

6. Start Coding!

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

   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

1. You write your code

2. wuchale auto extracts the messages into the catalog files

   During this step, if configured, AI 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, AI 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.

Tip

What’s next?

• Learn about the default Extraction rules and how to customize them
• Learn about Loading catalogs to do it exactly the way you want
• Learn about How it works

Or you can read any of the other relevant guides.