Wuchale

https://wuchale.dev/
Admin
Wuchale is an internationalization (i18n) tool that automatically extracts and translates strings...
Tokens:43,564
Snippets:689
Trust Score:5.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Wuchale Package

Source: https://wuchale.dev/intro/start

Install the Wuchale package using npm. This is the first step for any project setup.

```bash
npm install wuchale
```

--------------------------------

### Configure Multiple Adapters

Source: https://wuchale.dev/guides/multiple-adapters

Example of configuring multiple adapters with distinct keys in the wuchale configuration. This setup allows for different adapter types or configurations to coexist.

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


export default defineConfig({
    locales: ['en', 'es'],
    adapters: {
        server: vanilla(),
        client: jsx(),
    }
})
```

--------------------------------

### Adapter Configuration Example

Source: https://wuchale.dev/reference/adapter-api

Example of how an adapter is configured in `wuchale.config.js`. It shows passing configuration values to the adapter function.

```javascript
adapter({
    confKey: value,
    ...
})
```

--------------------------------

### Check wuchale status command help

Source: https://wuchale.dev/guides/cli

Get help for the 'status' command, which shows setup information like loader file existence, message counts, and translation status.

```bash
$ npx wuchale status --help
```

--------------------------------

### Install Base Package and Svelte Adapter

Source: https://wuchale.dev/intro/start

Install the core wuchale package and the adapter for Svelte projects.

```bash
npm install wuchale @wuchale/svelte
```

--------------------------------

### Install Vite Plugin Package

Source: https://wuchale.dev/changelogs/wuchale

Install the new Vite plugin package to integrate Wuchale with Vite.

```bash
npm install -D @wuchale/vite-plugin
```

--------------------------------

### Loading Configuration Example

Source: https://wuchale.dev/changelogs/wuchale

Configuration for granular and direct loading with grouping for specific files.

```javascript
return defaultGenerateLoadID(filename)
          },
          loading: {
              granular: true,
              direct: true,
              group: [
                  '**/*grouped*', 
              ]
          }
       }),
    }
})

```
```

--------------------------------

### Install Base Package and JSX Adapter

Source: https://wuchale.dev/intro/start

Install the core wuchale package and the adapter for JSX-based projects like React or SolidJS.

```bash
npm install wuchale @wuchale/jsx
```

--------------------------------

### Get CLI Help

Source: https://wuchale.dev/guides/cli

Run the CLI with the --help flag to display all available commands and options.

```bash
$ npx wuchale --help
```

--------------------------------

### Example of Main Svelte Adapter Configuration

Source: https://wuchale.dev/reference/adapter-common

Illustrates how to configure the main Svelte adapter with a source locale.

```javascript
// ...
main: svelte({
    sourceLocale: 'es',
}),
// ...
```

--------------------------------

### Testing Library setup for client-side catalog loading

Source: https://wuchale.dev/guides/testing

Use this setup with Testing Library to test client-side catalog loading. It requires importing `loadLocale` and rendering the component to test its behavior.

```javascript
import { expect, test } from 'vitest';
import { greet } from './hello.svelte.js';


import { loadLocale } from 'wuchale/load-utils';


import Hello from './hello.svelte'
import {render, screen} from '@testing-library/svelte'


// test with Spanish
await loadLocale('es')


test('Greeting', () => {
    render(Hello)


    const button = screen.getByRole('button', {name: 'Hola'})
    expect(button).toBeInTheDocument()
})
```

--------------------------------

### URL Pattern Translation Example

Source: https://wuchale.dev/guides/urls

Example of a translated URL pattern in a .po file. The 'url:{adapterKey}' flags indicate its usage.

```gettext
#: main
#, url:main,url:js
msgid "/items/**"
msgstr "/elementos/**"
```

--------------------------------

### Vitest setup for server-side catalog loading

Source: https://wuchale.dev/guides/testing

Use this setup with Vitest to test server-side catalog loading. Ensure all necessary locales and loaders are imported and loaded before running tests.

```javascript
import { expect, test } from 'vitest';
import { greet } from './hello.svelte.js'; // to be tested


import * as main from '../locales/main.loader.server.svelte.js'
import * as js from '../locales/js.loader.server.js'


import { loadLocales, runWithLocale } from 'wuchale/load-utils/server';
import { locales } from '../locales/data.js'


await loadLocales(main.key, main.loadCount, main.loadCatalog, locales)
await loadLocales(js.key, js.loadCount, js.loadCatalog, locales)


test('Greeting', () => {
    // test with Spanish
    runWithLocale('es', () => {
        let h = greet()
        expect(h).toEqual('Hola desde el módulo');
    })
});
```

--------------------------------

### Example HTML Snippet

Source: https://wuchale.dev/intro/howitworks

This is a basic HTML snippet used as an example for the localization process.

```html
<p>Hello</p>
```

--------------------------------

### Loader Placeholder Example

Source: https://wuchale.dev/reference/adapter-api

Example of using placeholders within loader files, which will be replaced by their actual values during runtime.

```javascript
export const key = '${KEY}'

```

--------------------------------

### Load Locale in App (Vite)

Source: https://wuchale.dev/intro/start

Example of how to load a locale dynamically in your application when using Vite. This is part of the setup for Vite projects.

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

--------------------------------

### Example .po file after translation

Source: https://wuchale.dev/intro/concepts

This example shows a .po file after it has been translated. The 'msgstr' fields now contain the translated text for each message ID.

```po
# ...other headers
"Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;\n"


#: src/path/to/source1.svelte
msgid "Hello world!"
msgstr "¡Hola Mundo!"


#: src/path/to/source2.svelte
msgid "Welcome"
msgstr "Bienvenido"
```

--------------------------------

### Manual Key Management Examples

Source: https://wuchale.dev/intro/approaches

Demonstrates different ways to reference translations using predefined keys in manual key management approaches.

```javascript
// Traditional approach
<p>{t('pages.home.greeting', {username})}</p>
```

```javascript
// Paraglide approach
<p>{m.welcome_message({username})}</p>
```

```javascript
// React-intl approach
<p><FormattedMessage id="greeting" values={{username}} /></p>
```

--------------------------------

### Example Link with Internationalized URL

Source: https://wuchale.dev/guides/urls

An example of an HTML anchor tag that will be processed during build time for URL internationalization.

```html
<a href="/items/foo/{itemId}">Item</a>
```

--------------------------------

### Plain HTML Example

Source: https://wuchale.dev/

Demonstrates writing plain HTML content that can be internationalized.

```html
<p>Hello world!</p>
```

--------------------------------

### Example DOM Manipulation

Source: https://wuchale.dev/intro/start

A simple JavaScript function to demonstrate DOM manipulation, showing how to set the innerHTML of an element. This is an example of 'Start Coding!'.

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

--------------------------------

### React Component Example

Source: https://wuchale.dev/intro/start

Example of a React component. Wuchale will automatically extract and compile translations from strings within your components.

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

--------------------------------

### HTML Content Example

Source: https://wuchale.dev/guides/fallback

This is an example of HTML content that will be extracted for translation.

```html
<p>Hello</p>
```

--------------------------------

### Full Automation Example

Source: https://wuchale.dev/intro/approaches

Illustrates how text can be automatically detected for translation without explicit marking, as used by Wuchale.

```javascript
<p>Hello {username}!</p>
```

--------------------------------

### Svelte Component Example

Source: https://wuchale.dev/intro/start

Example of a Svelte component. Wuchale will automatically extract and compile translations from strings within your components.

```html
<p>Hello world</p>
```

--------------------------------

### Custom Localization Logic Example

Source: https://wuchale.dev/guides/urls

An example of a custom `localize` function that returns the path directly if the host and locale match specific conditions, otherwise it prefixes the locale to the path.

```javascript
export function localize(path, locale) {
    const host = (new URL(location.href)).host
    if (host === 'example.com' && locale === 'en' || host === 'example.es' && locale === 'es') {
        return path
    }
    return `/${locale}/${path}`
}

```

--------------------------------

### Create Wuchale Configuration for React

Source: https://wuchale.dev/intro/start

Define Wuchale's locales and adapters. This example configures the main adapter for React using the 'react' loader.

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


export default defineConfig({
    locales: ['en', 'es'],
    adapters: {
        main: jsx({ loader: 'react' }),
    }
})
```

--------------------------------

### Provide Custom JSON Storage to Adapter

Source: https://wuchale.dev/guides/storage

Configuration example showing how to provide a custom storage handler, like the `jsonHandler` created previously, to a Wuchale adapter.

```javascript
export default {
    // ...
    adapters: {
        main: svelte({
            // ...
            storage: jsonHandler,
        })
    }
}
```

--------------------------------

### Writing an Adapter Creator Function

Source: https://wuchale.dev/reference/adapter-api

Example of a general adapter creator function using `deepMergeObjects` to handle default arguments and return a configured adapter object.

```javascript
import { deepMergeObjects } from 'wuchale' // a utility to merge config objects with defaults.


type FooArgs = AdapterArgs<LoadersAvailable>


const defaultArgs: FooArgs = {
    // ...
}


export const adapter = (args: Partial<FooArgs> = defaultArgs): Adapter => {
    let { 
        heuristic,
        patterns,
        runtime,
        loader,
        ...rest
    } = deepMergeObjects(args, defaultArgs)
    // prep logic...
    return {
        transform: ({ content, filename, index, expr, matchUrl }) => {
            // transform logic...
            return {
                output: {code: '...', map: {/*...*/} },
                msgs: [/*...*/],
            }
        },
        loaderExts: ['.js', '.ts'],
        defaultLoaderPath: '...',
        runtime,
        getRuntimeVars: {
            plain: '_w_load_',
            reactive: '_w_load_rx_',
        },
        ...rest,
    }
}
```

--------------------------------

### Example .po file before translation

Source: https://wuchale.dev/intro/concepts

This is the default catalog storage format for messages before they have been translated. It includes metadata headers and untranslated messages.

```po
# ...other headers
"Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;\n"


#: src/path/to/source1.svelte
msgid "Hello world!"
msgstr ""


#: src/path/to/source2.svelte
msgid "Welcome"
msgstr ""
```

--------------------------------

### Create Wuchale Configuration for SolidJS

Source: https://wuchale.dev/intro/start

Define Wuchale's locales and adapters for SolidJS. This example configures the main adapter for SolidJS using the 'solidjs' loader and variant.

```javascript
// @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',
        }),
    }
})
```

--------------------------------

### SolidJS App with Loader

Source: https://wuchale.dev/adapters/jsx

Example of a SolidJS application that shows a loading indicator while translations are being fetched. This ensures a smoother user experience by hiding incomplete content.

```jsx
import { createEffect, createSignal, Show } from 'solid-js';
import { loadLocale } from 'wuchale/load-utils'


import styles from './App.module.css';


const App = () => {
    const [locale, setLocale] = createSignal('en')
    const [loaded, setLoaded] = createSignal(false)
    createEffect(() => {
        setLoaded(false)
        loadLocale(locale()).then(() => setLoaded(true))
    })
    return (
        <Show when={loaded()} fallback={/* @wc-ignore */ 'Loading translations...'}>
            {/* Your JSX */}
        </Show>
    );
};


```

--------------------------------

### English Translations

Source: https://wuchale.dev/

Example of English translation strings using msgid and msgstr.

```gettext
msgid "Hello!"
msgstr "Hello!"


msgid "Welcome"
msgstr "Welcome"


msgid "Welcome {0}!"
msgstr "Welcome {0}!"

```

--------------------------------

### Rendering Translated Content

Source: https://wuchale.dev/

Example of the final rendered output with Spanish translation.

```html
<p>¡Hola Mundo!</p>
```

--------------------------------

### Migrate Storage from pofile to json

Source: https://wuchale.dev/guides/storage

Use `migrateStorage` to temporarily migrate translations between storage drivers. This example shows migrating from `pofile` to `json`.

```javascript
import { defineConfig, pofile, migrateStorage } from "wuchale";
import { json } from "@wuchale/json";


export default defineConfig({
  // ...
  adapters: {
    main: svelte({
      // ...
      storage: migrateStorage([pofile()], json()),
    }),
  },
});
```

--------------------------------

### Extraction Rules Example

Source: https://wuchale.dev/adapters/vanilla

Illustrates wuchale's default extraction rules for the Vanilla adapter. Only messages within function definitions are extracted; standalone variables are ignored.

```javascript
const message = 'This is not extracted'
const lowercase = 'not extracted'


function foo() {
    const extracted = 'Hello!'
}
```

--------------------------------

### Spanish Translations

Source: https://wuchale.dev/

Example of Spanish translation strings using msgid and msgstr.

```gettext
msgid "Hello!"
msgstr "¡Hola!"


msgid "Welcome"
msgstr "Bienvenido"


msgid "Welcome {0}!"
msgstr "¡Bienvenido {0}!"

```

--------------------------------

### Configuring Svelte Adapter with Custom Heuristic

Source: https://wuchale.dev/adapters/svelte

Example of configuring the Svelte adapter for SvelteKit, specifying a custom heuristic to control the auto-wrapping of top-level strings in `$derived`.

```javascript
import { adapter as svelte, svelteDefaultHeuristicDerivedReq } from "@wuchale/svelte"
import { defineConfig } from "wuchale"


export default defineConfig({
    locales: ['en', 'es'],
    adapters: {
        main: svelte({
            loader: 'sveltekit', // e.g.
            heuristic: svelteDefaultHeuristicDerivedReq,
        }),
        // ...
    },
    // ...
}
```

--------------------------------

### Defining a Custom Currency Function for Localization

Source: https://wuchale.dev/changelogs/wuchale

Example of defining a pure function for currency localization that can be used with Wuchale's pattern system.

```javascript
function currency(num, loc = "en") {
  return new Intl.NumberFormat(loc, {
    style: "currency",
    currency: "EUR",
  }).format(num);
}
```

--------------------------------

### Basic JavaScript Function

Source: https://wuchale.dev/adapters/vanilla

A standard JavaScript function example. This snippet is for general usage within your application.

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

--------------------------------

### React App with Loader

Source: https://wuchale.dev/adapters/jsx

Example of a React application that displays a loading message until translations are loaded. This approach prevents flickering of messages.

```jsx
import { useEffect, useState } from 'react'
import './App.css'
import { loadLocale } from 'wuchale/load-utils'


function App() {
    const [locale, setLocale] = useState('en')
    const [loaded, setLoaded] = useState(false)
    useEffect(() => {
        setLoaded(false)
        loadLocale(locale).then(() => setLoaded(true))
    }, [locale])
    if (!loaded) {
        // @wc-ignore
        return 'Loading translations...'
    }
    return (
        {/* Your JSX */}
    )
}

```

--------------------------------

### Component for client-side testing

Source: https://wuchale.dev/guides/testing

This is a simple button component used for client-side testing examples.

```html
<button>Hello</button>
```

--------------------------------

### Separate Storage by Locale

Source: https://wuchale.dev/guides/storage

Use `storageByLocale` to partition translations based on locale. This example stores English messages in `pofile` and Spanish/German messages in `json`.

```javascript
storage: storageByLocale([
    [['en'], pofile()],
    [['es', 'de'], json()],
  ]),
```

--------------------------------

### Extracted PO File Entry (Empty)

Source: https://wuchale.dev/intro/howitworks

An example of a message extracted into a .po file, with the translation string empty.

```gettext
msgid "Hello"
msgstr ""
```

--------------------------------

### Transformed Module Import Example

Source: https://wuchale.dev/guides/loading

Transformed modules import `getRuntime` or `getRuntimeRx` from the loader file and call it with a `loadID` to obtain a `Runtime` object.

```javascript
import {getRuntime as _w_load_, getRuntimeRx as _w_load_rx_} from "../locales/main.loader.js"
const _w_runtime_ = _w_load_('key') // plain
const _w_runtime_ = _w_load_rx_('key') // reactive
```

--------------------------------

### Runtime Pluralization with Locale Data

Source: https://wuchale.dev/guides/plurals-l10n

Example of using wuchale's runtime loader in a Svelte component to dynamically apply locale-specific pluralization rules.

```svelte
<script>
    import _w_rt_ from '../locales/main.loader.svelte.js'
    const _w_runtime_ = _w_rt_('main')
    import {plural} from '/src/utils.js'
    let itemCount = 5
</script>


<p>{plural(itemCount, _w_runtime_.p(0), _w_runtime_._.p)}</p>
```

--------------------------------

### Granular Compiled Catalog - Part 1

Source: https://wuchale.dev/intro/concepts

Example of a compiled catalog when granular loading is enabled, containing a subset of messages from a source file. This helps reduce bundle size by loading only necessary translations.

```javascript
export const c = ["¡Hola Mundo!"]
export const p = n => n == 1 ? 0 : 1
```

--------------------------------

### Extracted PO File Entry (Translated)

Source: https://wuchale.dev/intro/howitworks

An example of a message extracted into a .po file, with the translation string pre-filled (e.g., for the source locale).

```gettext
msgid "Hello"
msgstr "Hello"
```

--------------------------------

### Granular Compiled Catalog - Part 2

Source: https://wuchale.dev/intro/concepts

Another example of a compiled catalog for granular loading, containing a different subset of messages. Multiple such catalogs can exist per locale when granular loading is active.

```javascript
export const c = ["Bienvenido"]
export const p = n => n == 1 ? 0 : 1
```

--------------------------------

### Separate Storage by Message Type

Source: https://wuchale.dev/guides/storage

Use `storageByType` to direct different types of translations (e.g., messages, URLs) to distinct storage drivers. This example stores URL translations in `json` and normal messages in `pofile`.

```javascript
storage: storageByType({
    message: pofile(),
    url: json()
  }),
```

--------------------------------

### Basic wuchale Configuration with Svelte Adapter

Source: https://wuchale.dev/reference/config

This snippet demonstrates a basic configuration for wuchale using the Svelte adapter. It specifies the locales and the adapter configuration, including the catalog path.

```javascript
// @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}',
        }),
    }
})
```

--------------------------------

### Configure Pluggable Storage Handler

Source: https://wuchale.dev/changelogs/wuchale

Set up pluggable storage handlers by specifying a storage implementation in the adapter configuration. The 'storage' key accepts any implementation matching the expected shape for a storage collection.

```javascript
export default {
  // ...
  adapters: {
    main: svelte({
      // ...
      storage: pofile({ dir: "..." }),
    }),
  },
};
```

--------------------------------

### Get Language Names in English

Source: https://wuchale.dev/guides/tips

Use Intl.DisplayNames to get language names in English. This is useful for displaying language options in a user interface.

```javascript
// Get display names of language in English
const languageNamesEn = new Intl.DisplayNames(["en"], { type: "language" });
languageNamesEn.of("en-US"); // "English (United States)"
languageNamesEn.of("es"); // "Spanish"
languageNamesEn.of("fr"); // "French"
```

--------------------------------

### Get Language Names in Spanish

Source: https://wuchale.dev/guides/tips

Use Intl.DisplayNames to get language names in Spanish. This allows for displaying language options in the user's preferred language.

```javascript
// Spanish in Spanish
const languageNamesEs = new Intl.DisplayNames(["es"], { type: "language" });
languageNamesEs.of("es"); // "español"
```

--------------------------------

### Configure JSON Storage with Location

Source: https://wuchale.dev/changelogs/json

Demonstrates how to configure JSON storage using the `location` option for specifying file paths with locale placeholders. This replaces the older `dir` configuration.

```javascript
import { pofile } from 'wuchale'
import { pofile, storageByType } from 'wuchale'


export default {
    // ...
    adapters: {
        main: svelte({
            // ...
            storage: pofile({dir: 'src/locales'}),
            storage: storageByType({
                message: pofile({location: 'src/locales/{locale}.po'})
            }),
        }),
    }
}
```

--------------------------------

### Basic Loader Implementation

Source: https://wuchale.dev/guides/loading

A basic loader file prepares a catalog module, creates a runtime object using `toRuntime`, and exports `getRuntime` and `getRuntimeRx` to provide this runtime object.

```javascript
import toRuntime from 'wuchale/runtime'


// prepare/load the catalog
const catalogModule = {c: ['Hello'], p: n => n == 1 ? 0 : 1}
const rt = toRuntime(catalogModule, 'en')


export const getRuntime = loadID => {
    return rt
}


export const getRuntimeRx = loadID => {
    // do something different if needed for reactivity
    return rt
}
```

--------------------------------

### PO File Options Configuration

Source: https://wuchale.dev/guides/storage

Configure the directory for PO catalogs and whether to keep URLs in separate catalogs.

```typescript
type POFileOptions = {
    /** in the form like 'path/to/dir/{locale}.po' */
    location: string
}
```

--------------------------------

### Configure Wuchale Runtime for SvelteKit SSR

Source: https://wuchale.dev/changelogs/svelte

Configure the runtime to wrap initialization and expressions for SvelteKit SSR compatibility. Load catalogs in `hooks.server.js` for server-side locale handling.

```javascript
import type { Handle } from "@sveltejs/kit";
import { loadCatalog, loadIDs, key } from "./locales/loader.svelte.js";
import { runWithLocale, loadLocales } from "wuchale/load-utils/server";


await loadLocales(key, loadIDs, loadCatalog, ["en", "es", "fr"]);


export const handle: Handle = async ({ event, resolve }) => {
  const locale = event.url.searchParams.get("locale") ?? "en";
  return await runWithLocale(locale, async () => {
    return await resolve(event, {});
  });
};
```

```javascript
main: adapter({
        runtime: {
            wrapInit: expr => `() => ${expr}`,
            wrapExpr: expr => `${expr}()`,
        }
    }),
```

--------------------------------

### Compiled Catalog (Spanish)

Source: https://wuchale.dev/

Example of a compiled translation catalog for Spanish, represented as an array.

```javascript
export let c = ["¡Hola Mundo!"]
```

--------------------------------

### Compiled Catalog (English)

Source: https://wuchale.dev/

Example of a compiled translation catalog for English, represented as an array.

```javascript
export let c = ["Hello world!"]
```

--------------------------------

### Configure Wuchale with Astro Adapter

Source: https://wuchale.dev/intro/start

Set up Wuchale configuration for Astro projects. This includes defining locales and specifying the Astro adapter.

```javascript
// @ts-check
import { adapter as astro } from "@wuchale/astro"
import { defineConfig } from "wuchale"


export default defineConfig({
    locales: ['en', 'es'],
    adapters: {
        main: astro(),
    }
})
```

--------------------------------

### Example of topLevelCall property

Source: https://wuchale.dev/reference/adapter-common

Illustrates how the 'topLevelCall' property captures the name of the top-level function call in a code snippet.

```javascript
const a = topLevel({
    bar: non.topLevel('Hello'),
})

```

--------------------------------

### Configuring Custom Patterns for Localization

Source: https://wuchale.dev/changelogs/wuchale

Demonstrates how to configure custom localization patterns within the Wuchale adapter settings, specifying the pattern name and its arguments.

```javascript
// ...
    adapters: {
        main: svelte({
            loader: 'sveltekit',
            patterns: [
                {name: 'currency', args: ['other', 'locale']},
            ]
        }),
// ...
```

--------------------------------

### Exporting a greet function

Source: https://wuchale.dev/guides/testing

This is the function to be tested. It returns a greeting string.

```javascript
export const greet = () => {
    return 'Hello from module' // extracted/translated by wuchale
}
```

--------------------------------

### Directly Import Compiled Catalogs

Source: https://wuchale.dev/guides/loading

Import compiled catalog modules synchronously. Ensure the file path matches the compiled output structure.

```javascript
import * as enCatalog from '../locales/.wuchale/main.main.en.compiled.js'
import * as esCatalog from '../locales/.wuchale/main.main.es.compiled.js'


const catalogs = {
    en: enCatalog,
    es: esCatalog,
}
```

--------------------------------

### Wuchale Multiple Adapters Configuration

Source: https://wuchale.dev/guides/multiple-adapters

Configure multiple Wuchale adapters for a SvelteKit application, demonstrating shared catalogs between 'single' and 'server' adapters.

```typescript
// @ts-check
import { defineConfig, pofile } from "wuchale"
import { adapter as svelte } from '@wuchale/svelte'
import { adapter as vanilla } from "wuchale/adapter-vanilla"


export default defineConfig({
    locales: ['en', 'es-es'],
    adapters: {
        // Applies over the components inside the single route as well as the top level route.
        // Uses a single compiled catalog per locale, downloaded once.
        single: svelte({
            loader: 'sveltekit',
            storage: pofile({location: './src/locales/single/{locale}.po'})
            files: [
                './src/routes/{single,server}/**/*.svelte',
                './src/routes/single/**/*.svelte.{js,ts}',
                './src/routes/*.svelte',
                './src/routes/*.svelte.{js,ts}'
            ],
        }),
        // Applies over the granular route.
        // Uses one compiled catalog per locale per each file/component
        //   unless they contain 'grouped' in which case they will share one compiled catalog.
        // Which one to download is decided at runtime
        granularLoad: svelte({
            loader: 'sveltekit',
            files: './src/routes/granular/**/*.svelte',
            storage: pofile({location: './src/locales/granular/{locale}.po'})
            loading: {
                granular: true,
                group: [
                    '**/*grouped*',
                ]
            }
        }),
        // Applies over the granular-bundle route.
        // Each file directly imports all locale variants of its own catalog,
        //   even though only one will be selected at runtime.
        // It only takes the locale identifier string from the loader at runtime.
        // This mimicks how ParaglideJS downloads catalogs but is not recommended.
        granularLoadBundle: svelte({
            loader: 'sveltekit',
            files: './src/routes/granular-bundle/**/*.svelte',
            storage: pofile({location: './src/locales/granular-bundle/{locale}.po'})
            loading: {
                granular: true,
                direct: true,
            }
        }),
        // Used for messages that are sent from the server instead of being rendered client-side.
        // Uses one compiled catalog because bundle size optimizations are irrelevant on the server.
        // It is necessary to write the loader proxy and the compiled catalogs to disk
        //   because node.js doesn't support virtual modules.
        // Also since node.js is not a reactive environment, we have to initialize the runtime inside functions.
        server: vanilla({
            loader: 'server',
            storage: pofile({location: './src/locales/single/{locale}.po'})
            files: './src/**/*.server.{js,ts}',
        }),
    },
})

```

--------------------------------

### Synchronous Proxy for Catalog Loading

Source: https://wuchale.dev/guides/loading

Use a synchronous proxy to load catalog modules by loadID and locale. This simplifies the process compared to manual imports.

```javascript
import toRuntime from 'wuchale/runtime'
import { loadCatalog, loadCount } from './.wuchale/main.proxy.sync.js'


let locale = 'en' // maybe controlled by state
const locales = ['en', 'es']
const runtimes = []


for (let loadID = 0; loadID < loadCount; loadID++) {
    runtimes[loadID] = runtimes[loadID] ?? {}
    for (const locale of locales) {
        runtimes[loadID][locale] = toRuntime(loadCatalog(loadID, locale), locale)
    }
}


export const getRuntimeRx = loadID => runtimes[loadID]?.[locale]
export const getRuntime = getRuntime
```

--------------------------------

### Comparison of i18n Syntax

Source: https://wuchale.dev/intro/why

Illustrates how wuchale integrates with plain code, contrasting it with traditional i18n solutions that require explicit function calls or components.

```html
<p><Trans>Hello</Trans></p>
<!-- Paraglide -->
<p>{t.welcome_message()}</p>
<!-- Lingui, i18next and many others -->
<p>{t('home.welcome.greeting')}</p>
```

--------------------------------

### Example of Untranslated and Mistranslated Messages

Source: https://wuchale.dev/guides/ai

Illustrates initial untranslated messages and a subsequent incorrect translation output, highlighting the need for mistake handling.

```text
msgid "Hello!"
msgstr ""


msgid "Welcome"
msgstr ""


msgid "Welcome {0}!"
msgstr ""
```

```text

msgid "Hello" 
msgstr "Hola"


msgid "Welcom-"
msgstr "Bienven-"


msgid "Welcome {0}!"
msgstr ""
```

--------------------------------

### Use Proper Hook Name for React Reactive Runtime

Source: https://wuchale.dev/changelogs/wuchale

Used the correct hook name to get the reactive runtime in React applications.

```git-commit
f861f78: Use proper hook name to get reactive runtime in React #181
```

--------------------------------

### Use `_w_runtime_` for Bundle Size Reduction

Source: https://wuchale.dev/changelogs/wuchale

Switched from `_w_runtime_.t(...)` to `_w_runtime_(...)` to further reduce bundle size.

```git-commit
f92c641: Use `_w_runtime_(...)` instead of `_w_runtime_.t(...)` to further reduce bundle size
```

--------------------------------

### Configure Vite Plugin

Source: https://wuchale.dev/guides/bundlers

Integrate the Wuchale Vite plugin into your Vite project configuration. This snippet shows the basic setup for including the plugin.

```javascript
import { defineConfig } from 'vite'
import { wuchale } from 'wuchale/vite'


export default defineConfig({
    plugins: [ wuchale({/* config */}) ],
})
```

--------------------------------

### Import Adapter Key

Source: https://wuchale.dev/changelogs/svelte

Import the adapter key from proxies to avoid manually updating them if changed in the config.

```javascript
import { key } from "virtual:wuchale/proxy";
```

--------------------------------

### Direct Loading Configuration

Source: https://wuchale.dev/guides/loading

When using `loading.direct`, the loader function receives an object with locales as keys and runtime objects as values. The loader then simply selects and returns the appropriate runtime.

```javascript
// any state store for the locale
let locale = 'en'


export const getRuntime = (runtimes) => runtimes[locale]
export const getRuntimeRx = getRuntime
```

--------------------------------

### Create Wuchale Configuration for SvelteKit

Source: https://wuchale.dev/intro/start

Define Wuchale's locales and adapters for SvelteKit. This configures the main adapter for SvelteKit and a vanilla JS adapter for specific files.

```javascript
// @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}',
            ],
        })
    }
})
```

--------------------------------

### Check wuchale check command help

Source: https://wuchale.dev/guides/cli

Get help for the 'check' command, used to verify translation catalog integrity and detect potential errors.

```bash
$ npx wuchale check --help
```

--------------------------------

### SvelteKit Nested Layouts: Awaiting Parent Load

Source: https://wuchale.dev/adapters/svelte

Demonstrates how to await the parent layout's load function in nested SvelteKit layouts to ensure proper catalog loading order.

```typescript
/** @type {import('./$types').LayoutLoad} */
export const load = async ({ parent }) => {
    await parent()
    return {
        nestedMsg: 'Hello from nested layout'
    }
}

```

--------------------------------

### Configure Vite for Astro

Source: https://wuchale.dev/intro/start

Integrate Wuchale into your Vite configuration for Astro projects. This setup also includes Astro's i18n routing configuration.

```javascript
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,
        }
    },
});
```

--------------------------------

### Add CLI Commands to package.json

Source: https://wuchale.dev/guides/cli

Conveniently add wuchale commands to your package.json scripts for easier execution.

```json
// ...
"scripts": {
    // ...
    "extract": "wuchale",
    "clean": "wuchale --clean"
},
// ...
```

--------------------------------

### Configure Locales and Adapters

Source: https://wuchale.dev/changelogs/jsx

Configure source and other locales, and specify adapter configurations. The source locale on the adapter defaults to the first locale in the main locales array.

```javascript
{
    sourceLocale: 'en',
    otherLocales: ['es', 'fr'],
    locales: ['en', 'es', 'fr'],
    adapters: {
        main: svelte({
            sourceLocale: 'en',
            // ...
        })
    }
}
```

--------------------------------

### Register Client-Side Loaders with Custom Collection

Source: https://wuchale.dev/guides/loading

Integrate Wuchale's loading with framework reactivity using a custom CatalogCollection. The defaultCollection helper can create a collection from a state object.

```javascript
import { loadCatalog, loadCount } from './.wuchale/main.proxy.js'
import { registerLoaders, defaultCollection } from 'wuchale/load-utils'


const key = 'main'


const catalogs = $state({})


export const getRuntimeRx = registerLoaders(key, loadCatalog, loadCount, defaultCollection(catalogs))
export const getRuntime = getRuntimeRx

```

--------------------------------

### PO File Header for Plural Forms

Source: https://wuchale.dev/guides/plurals-l10n

Example of a PO file header defining plural forms for Spanish. It specifies the number of plurals and the rule for selecting them.

```po
msgid ""
msgstr ""
"...{other headers}"
"Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;\n"
```

--------------------------------

### Svelte Component with Reactive Message (Default)

Source: https://wuchale.dev/guides/reactivity

Example of a Svelte component using a top-level variable for a message, which wuchale's reactivity system would typically update.

```html
<script>
const msg = 'Hello'
</script>


<p>{msg}</p>
```

--------------------------------

### Multiple Adapter Configurations

Source: https://wuchale.dev/guides/loading

Configure multiple adapters to manage translation catalogs separately for different parts of your application, such as 'product' and 'services'. This is beneficial when you have many files but a moderate number of messages per file, allowing files within an adapter to share catalogs.

```javascript
export default defineConfig({
    locales: ['en', 'es'],
    adapters: {
        product: svelte({
            files: ['src/product/**/*.svelte'],
            localesDir: 'src/product/locales',
        }),
        services: svelte({
            files: ['src/services/**/*.svelte'],
            localesDir: 'src/services/locales',
        }),
        // ...
    }
})
```

--------------------------------

### Configure Wuchale with Vanilla Adapter and Vite Loader

Source: https://wuchale.dev/intro/start

Configure Wuchale for vanilla JavaScript projects when using Vite. Specify the loader as 'vite'.

```javascript
// @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'
        })
    }
})
```

--------------------------------

### Define Custom Pluralization Function

Source: https://wuchale.dev/guides/plurals-l10n

Define a reusable function to select the correct message from candidates based on a number. The function signature must match the example provided.

```javascript
export function plural(num, candidates, rule = n => n === 1 ? 0 : 1) {
    const index = rule(num)
    return candidates[index].replace('#', num)
}
```

--------------------------------

### Composable Storage: dir to location in pofile and json

Source: https://wuchale.dev/changelogs/wuchale

The `dir` config for `pofile` and `json` storage has been renamed to `location`. If `separateUrls` was used, migrate to `storageByType`.

```javascript
import { pofile } from 'wuchale'
import { pofile, storageByType } from 'wuchale'


export default {
    // ...
    adapters: {
        main: svelte({
            // ...
            storage: pofile({dir: 'src/locales'}),
            storage: storageByType({
                message: pofile({location: 'src/locales/{locale}.po'})
            }),
        }),
    }
```

--------------------------------

### Svelte SPA: Loading Locale with Effect

Source: https://wuchale.dev/adapters/svelte

This Svelte SPA setup loads the locale using a reactive effect, suitable for dynamic locale changes within the application.

```svelte
<script>
  import { loadLocale } from 'wuchale/load-utils'
  // so that the loaders are registered first
  import './locales/main.loader.svelte.js'
  // you can use any state from anywhere for the locale
  let locale = $state('en')
  $effect(() => {
      loadLocale(locale)
  })
</script>


<!-- Your app content -->

```

--------------------------------

### PO File Entry for Pluralization

Source: https://wuchale.dev/guides/plurals-l10n

Example of how the ICU pluralization string appears in a PO file (catalog storage). This entry includes the original English pluralization rules and placeholders for translation.

```gettext
msgid "\n"
"{numPhotos, plural,\n"
"=0 {You have no photos.}"
"=1 {You have one photo.}"
"other {You have # photos.}"
"}\n"
""
msgstr ""
"\n"
"{numPhotos, plural,\n"
"=0 {No tienes fotos.}"
"=1 {Tienes una foto.}"
"other {Tienes # fotos.}"
"}\n"
""
```

--------------------------------

### Use ICU Pluralization in Messages

Source: https://wuchale.dev/guides/plurals-l10n

Utilize ICU's pluralization syntax within your message strings. This example shows how to handle zero, one, and other plural forms for a 'numPhotos' variable.

```javascript
const msg = formatMsg(
  `{numPhotos, plural,
      =0 {You have no photos.}
      =1 {You have one photo.}
      other {You have # photos.}
    }`,
  { numPhotos: 1000 }
);
```

--------------------------------

### Attribute Extraction Logic

Source: https://wuchale.dev/guides/rules

Demonstrates attribute extraction rules, including URL extraction for 'href' and ignoring attributes starting with lowercase letters or specific attributes like 'method' on forms.

```html
<img alt="Profile Picture" class="not-extracted" />
<a href="/extracted/if/matching">Link</a>
```

--------------------------------

### Use Custom Intl.MessageFormat Utility Function

Source: https://wuchale.dev/changelogs/svelte

Utilize a custom internationalization utility function 'formatMsg' to format messages with pluralization rules. This example demonstrates formatting a message with different plural forms.

```javascript
const msg = formatMsg(
  `{numPhotos, plural,
      =0 {You have no photos.}
      =1 {You have one photo.}
      other {You have # photos.}
    }`,
  { numPhotos: 1000 }
);
```

--------------------------------

### File System (FS) Interface Definition

Source: https://wuchale.dev/reference/storage

Defines the file system abstraction layer provided by wuchale, including methods for reading, writing, creating directories, and checking file existence.

```typescript
type FS = {
    read(file: string): string | null | Promise<string | null>
    write(file: string, content: string): void | Promise<void>
    mkdir(path: string): void | Promise<void>
    exists(path: string): boolean | Promise<boolean>
    unlink(path: string): boolean | Promise<boolean>
}
```

--------------------------------

### Custom JSON Storage Data Structure

Source: https://wuchale.dev/guides/storage

Example data structure for a custom JSON storage handler, illustrating how plural rules and message items are represented. Note the use of `Map` objects.

```javascript
const data = {
    pluralRules: new Map([
        ['en', { nplurals: 2, plural: 'n == 1 ? 0 : 1' }],
        ['es', { nplurals: 2, plural: 'n == 1 ? 0 : 1' }],
    ]),
    items: [
        // this is a message item
        {
            id: ['Welcome'],
            translations: new Map([
                ['en', ['Welcome']],
                ['es', ['Bienvenido']],
            ]),
            references: [{ file: 'src/routes/page.svelte', refs: [ null ] }],
            urlAdapters: []
        },
        // this is a URL item
        {
            id: ['/items/{0}'],
            context: 'original: /items/*rest',
            translations: new Map([
                ['en', ['/items/{0}']],
                ['es', ['/elementos/{0}']],
            ]),
            references: [{ file: 'src/routes/page.svelte', refs: [ { link: '/items/{0}/details', placeholders: [[0, 'id']] } ] }],
            urlAdapters: ['main']
        }
    ]
}
```

--------------------------------

### Svelte Third-Party Package Adapter Configuration

Source: https://wuchale.dev/guides/third-party

Configure wuchale to internationalize a Svelte component library installed via npm. Specify the source locale and the path to the component files within node_modules.

```javascript
export default {
    locales: ['es', 'de'],
    adapters: {
        // other adapters for our files
        lib: svelte({
            loader: 'sveltekit',
            sourceLocale: 'en',
            files: 'node_modules/foo/dist/*.svelte'
        })
    }
}
```

--------------------------------

### Set Gemini API Key

Source: https://wuchale.dev/guides/ai

Set your Gemini API key as an environment variable to enable translation. Obtain your key from Google AI Studio.

```bash
export GEMINI_API_KEY=your_api_key
```

--------------------------------

### De-localization using SvelteKit Hooks

Source: https://wuchale.dev/guides/urls

Implement de-localization within SvelteKit's `hooks.js` file to remove locale prefixes from incoming URLs before routing. This example uses helper functions `deLocalize` and `matchUrl`.

```javascript
import { matchUrl } from './locales/single.url.js'
import { deLocalize } from './lib/url.js' // just an example
import { locales } from './locales/data.js'


/** @type {import('@sveltejs/kit').Reroute} */
export const reroute = ({url}) => {
    const [upath, locale] = deLocalize(url.pathname, locales)
    const {path} = matchUrl(upath, locale)
    return path ?? url.pathname
}

```

--------------------------------

### Update Loader Imports

Source: https://wuchale.dev/changelogs/svelte

Update imports from 'virtual:wuchale/loader' or 'virtual:wuchale/loader/sync' to 'virtual:wuchale/proxy' or 'virtual:wuchale/proxy/sync'.

```javascript
import ... from 'virtual:wuchale/loader'
// or
import ... from 'virtual:wuchale/loader/sync'
```

```javascript
import ... from 'virtual:wuchale/proxy'
// or
import ... from 'virtual:wuchale/proxy/sync'
```

--------------------------------

### Import Vite Plugin

Source: https://wuchale.dev/changelogs/wuchale

Import the Vite plugin from the new package in your vite.config.* file.

```javascript
import ... from '@wuchale/vite-plugin'
```
Tokens:
Raw