wuchale

wuchale is an innovative compile-time internationalization (i18n) toolkit designed for seamless integration into existing codebases without the need for code modifications. With wuchale, developers can write components in their natural syntax while the toolkit automatically handles the extraction and replacement of translatable strings during the build process.

Key Features

• No Extra Syntax Required: Write code normally; wuchale ensures functionality without additional annotations.
• Compact Catalogs: Translatable strings are stored as simple arrays, similar to Protobuf, eliminating the need for cumbersome keys.
• Effortless Integration: Incorporate i18n capabilities into projects without rewriting existing code.
• AI Translation: Leverage Gemini integration for automatic translations on-the-fly.
• Hot Module Replacement (HMR) Support: Enjoy live updates during development, including automatic AI translations.
• Minimal Dependencies: Requires fewer than five added dependencies, keeping the node_modules folder lean.
• Intelligent String Extraction: Employing AST analysis, the toolkit can deftly manage nested markup, conditionals, loops, and intricate interpolations.
• Compatibility with .po Files: Supports existing translation tools and workflows by utilizing standard .po files.

Why Choose wuchale?

Traditional i18n solutions often necessitate wrapping translatable strings in function calls or components. wuchale simplifies this process:

Traditional Example:

<p>{t('Hello')}</p>
<p><Trans>Welcome {userName}</Trans></p>

With wuchale:

<p>Hello</p>
<p>Welcome {userName}</p>

Getting Started

wuchale can be leveraged in various ways depending on the project structure:

• Standalone CLI for any JavaScript/TypeScript project.
• Vite Plugin for Vite-based projects using vanilla JS/TS.
• Framework Adapters for enhanced support in React/Preact, Svelte, and SolidJS.

Basic Usage Example

Once configured, components are written naturally:

// src/components/Welcome.jsx
function Welcome({ name }) {
  return (
    <div>
      <h1>Welcome to our app!</h1>
      <p>Hello, {name}! How are you today?</p>
      <button>Get started</button>
    </div>
  )
}

Run the following command to automatically extract translatable strings:

npx wuchale

This command generates .po files containing all translatable strings, ready for localization.

How It Works

wuchale employs static Abstract Syntax Tree (AST) analysis to:

1. Scan Source Code: Identify translatable text.
2. Extract Strings: Produce .po translation files.
3. Replace Strings: Use translation function calls linked to message indices.
4. Compile Compact Catalogs: Utilize arrays instead of string keys for efficient mapping.

Supported Features

• Complex Interpolations: Supports strings like Welcome {userName}, you have {count} messages.
• Nested Markup: Handles nested HTML structures such as <p>Visit our <a href="/help">help page</a> for more info</p>.
• Dynamic Content: Effectively processes conditional and looping structures.
• Live Translation Updates: Ensure real-time translations during development using HMR.

Documentation and Community

For further information, including examples and in-depth usage, visit the official documentation at wuchale.dev. Join the community for support and discussion on Discord or explore practical examples at wuchalejs/examples.

Contributing and Sponsorship

Contributions are encouraged, and sponsorship opportunities are available to support ongoing development.