wuchale i18n Toolkit

wuchale is a compile-time internationalization (i18n) toolkit designed to add translation capabilities to your project without requiring code changes or special syntax. It uses AST analysis to automatically extract translatable text from your source code at build time.

Key features:

• No extra syntax: Write standard components; no special t() functions or <Trans> components are required in your source.
• Framework agnostic: Supports React, Preact, Svelte(Kit), SolidJS, Astro, and plain JS/TS via specific adapters.
• Smart extraction: Handles nested markup, conditionals, loops, and complex interpolations automatically.
• Compact catalogs: Translations are compiled into tiny, index-based arrays for minimal bundle size.
• LLM support: Configurable integration for automatic translations using LLMs.
• Full URL support: Handles path translations (e.g., /about to /de/uber-uns).

The AIQueue uses a sophisticated mechanism to ensure translation quality and reliability:

1. Grouping: Items are grouped by locale using the group configuration. This ensures that related languages are sent in the same context to the LLM.
2. Batching: Items within a group are split into chunks defined by batchSize.
3. Validation: After receiving a response, AIQueue validates that:
   • The response is a valid JSON array.
   • The number of translated items matches the input.
   • For non-plural items, the translation is semantically equivalent to the source (using isEquivalent).
   • For plural items, the number of translated forms matches the source.
4. Retries: If validation fails or an error occurs, the queue identifies the unTranslated items and retries the translation for that specific subset. It will attempt this up to 30 times (MAX_RETRIES) before giving up.

The AdapterHandler follows a specific lifecycle to ensure translations are correctly extracted, stored, and served:

1. Initialization (create): Sets up file access, loads existing translation data into sharedState, and performs an initial compilation.
2. Extraction (transform): During file processing, the adapter identifies text items. These items are passed to handleTexts.
3. Storage Management (handleTexts): New keys are added to the sharedState.catalog, and references (which files use which keys) are tracked. If AI is enabled, items are queued for translation.
4. Compilation (compile / writeCompiled): The handler iterates through locales and generates optimized JavaScript modules (catalogs) containing the actual translation strings. It supports both global catalogs and granular catalogs (where translations are split by file/ID).
5. Runtime Injection: The handler prepares the necessary import headers (e.g., getRuntimeVars) so that the transformed code can access the translations via the adapter's runtime API.

wuchale transforms natural code into an optimized, index-based runtime.

Original Source (JSX):

function Welcome({ user }) {
  return (
    <div>
      <p><b>Hello, {user}</b>, and welcome!</p>
      <button>Get started</button>
    </div>
  )
}

Extracted Translation (.po):

msgid "<0>Hello, {0}</0>, and welcome!"
msgstr "<0>Hola, {0}</0>, y ¡bienvenido!"

msgid "Get started"
msgstr "Comenzar"

Compiled Catalog (JS):

export let c = [[[0, "Hola, ", 0], ", y ¡bienvenido!"], "Comenzar"]

Transformed Output (JSX):

import W_tx_ from "@wuchale/jsx/runtime.jsx"

function Welcome({ user }) {
  const _w_runtime_ = _w_load_rx_();
  return (
    <div>
      <p><W_tx_ t={[_w_ctx_ => <b key="_0"><W_tx_ x={_w_ctx_} n a={[user]} /></b>]} x={_w_runtime_.c(0)} /></p>
      <button>{_w_runtime_(1)}</button>
    </div>
  )
}

This process allows for indefinite nesting of markup (like the <b> tag above) while giving translators the freedom to reorder placeholders within the translated string.

// src/components/Welcome.jsx
function Welcome({ user }) {
  return (
    <div>
      <p><b>Hello, {user}</b>, and welcome!</p>
      <button>Get started</button>
    </div>
  )
}