Utilities

Internationalization (I18n)

Reach a global audience with built-in multi-language support. Translate strings, handle pluralization, and auto-detect user preferences.

Auto-Detection

Detects language from Headers, Cookies, or Query params.

Pluralization

Smart handling of plural forms (one/other).

Nested Keys

Organize translations with directory structure (lang/en/file.json).

Configuration

Default configuration is handled in your application creation or config.

src/app.ts

1// src/app.ts
2import { createApp } from "canxjs";
3
4const app = createApp({ 
5  port: 3000,
6  locale: 'en',
7  fallbackLocale: 'en'
8});

Translation Files

Create JSON files in your lang directory, organized by locale and filename.

lang/en/messages.json

1// lang/en/messages.json
2{
3  "welcome": "Welcome to our application",
4  "auth": {
5    "login": "Login",
6    "failed": "Invalid credentials"
7  },
8  "items": {
9    "one": "You have {count} item",
10    "other": "You have {count} items"
11  }
12}

Usage

Use the __ helper function to translate strings.

controller.ts

1import { __, trans, trans_choice } from "canxjs";
2
3// Basic translation
4__("messages.welcome"); // "Welcome to our application"
5
6// Nested keys
7__("messages.auth.login"); // "Login"
8
9// With parameters
10__("messages.greeting", { name: "Alice" }); 
11
12// Choice / Pluralization
13trans_choice("messages.items", 1, { count: 1 }); // "You have 1 item"
14trans_choice("messages.items", 5, { count: 5 }); // "You have 5 items"
15
16// Using Alias
17trans("messages.welcome");

Middleware

Use the middleware to automatically set the locale based on the request.

middleware.ts

1// Auto-detect locale from query, cookie, or header
2import { localizationMiddleware } from "canxjs";
3
4app.use(localizationMiddleware({
5    // detect: ['query', 'cookie', 'header'],
6    // queryKey: 'lang',
7    // cookieKey: 'locale'
8}));
9
10// GET /?lang=es -> sets locale to 'es'