I18n | Alepha

alepha@docs:~/docs/guides/frontend$
cat 5-i18n.md
2 min read
Last commit: 
#Internationalization (i18n)So you want to conquer the world market. First step: stop assuming everyone speaks English.
The @alepha/react/i18n module gives you SSR-friendly internationalization without the bloat. Lazy-loaded translations, type-safe keys, and automatic language detection.
#Setup
#Define DictionariesCreate translation files and register them with $dictionary:
typescript
// AppRouter.tsimport { $dictionary } from "@alepha/react/i18n"; class AppRouter {  en = $dictionary({    lazy: () => import("./translations/en.ts"),  });   fr = $dictionary({    lazy: () => import("./translations/fr.ts"),  });   de = $dictionary({    lazy: () => import("./translations/de.ts"),  });}
#Translation FilesEach translation file exports a default object:
typescript
// translations/en.tsexport default {  // Simple strings  welcome: "Welcome",  goodbye: "Goodbye",   // With placeholders  greeting: "Hello, {name}!",  items: "{count} items",   // Nested keys  nav: {    home: "Home",    about: "About Us",    contact: "Contact",  },   // Pluralization  messages: {    one: "You have 1 message",    other: "You have {count} messages",  },};
typescript
// translations/fr.tsexport default {  welcome: "Bienvenue",  goodbye: "Au revoir",  greeting: "Bonjour, {name}!",  items: "{count} articles",   nav: {    home: "Accueil",    about: "À propos",    contact: "Contact",  },   messages: {    one: "Vous avez 1 message",    other: "Vous avez {count} messages",  },};
#Using Translations
#The useI18n Hooktsx
import { useI18n } from "@alepha/react/i18n"; const Greeting = ({ user }) => {  const { tr, lang, setLang } = useI18n<AppRouter, "en">();   return (    <div>      <p>{tr("welcome")}</p>      <p>{tr("greeting", { name: user.name })}</p>      <p>{tr("nav.home")}</p>       {/* Language switcher */}      <select value={lang} onChange={(e) => setLang(e.target.value)}>        <option value="en">English</option>        <option value="fr">Français</option>        <option value="de">Deutsch</option>      </select>    </div>  );};
The type parameters are important:
AppRouter - Your router class with dictionaries
"en" - The default/fallback language for type inference
#What useI18n Returnstypescript
const {  tr,          // Translation function  lang,        // Current language code ("en", "fr", etc.)  setLang,     // Change language  l,           // Localization helper (dates, numbers)  dictionary,  // Raw dictionary object} = useI18n<AppRouter, "en">();
#Translation Function (tr)
#Simple Translationstsx
tr("welcome")           // "Welcome"tr("nav.home")          // "Home"
#With Placeholderstsx
tr("greeting", { name: "Alice" })  // "Hello, Alice!"tr("items", { count: 5 })          // "5 items"
#PluralizationDefine pluralized translations:
typescript
// en.tsmessages: {  zero: "No messages",  one: "You have 1 message",  other: "You have {count} messages",}
Use with count:
tsx
tr("messages", { count: 0 })  // "No messages"tr("messages", { count: 1 })  // "You have 1 message"tr("messages", { count: 5 })  // "You have 5 messages"
#FallbacksIf a key is missing, it falls back:
Try the requested key in current language
Try the same key in default language
Return the key itself (useful for debugging)
#Localization Helper (l)Format dates, numbers, and currencies:
tsx
const { l } = useI18n<AppRouter, "en">(); // Datesl(new Date(), { date: "short" })     // "1/15/24"l(new Date(), { date: "long" })      // "January 15, 2024"l(new Date(), { date: "fromNow" })   // "2 hours ago" // Numbersl(1234567.89, { number: "decimal" }) // "1,234,567.89"l(0.75, { number: "percent" })       // "75%" // Currencyl(99.99, { currency: "USD" })        // "$99.99"l(99.99, { currency: "EUR" })        // "€99.99"
Formatting respects the current locale:
tsx
// In Frenchl(1234567.89, { number: "decimal" }) // "1 234 567,89"l(99.99, { currency: "EUR" })        // "99,99 €"
#Language Detection
#Server-SideThe server detects language from:
URL parameter (?lang=fr)
Cookie (alepha.lang)
Accept-Language header
Default language
#Client-SideLanguage persists in a cookie. When setLang is called:
tsx
setLang("fr")  // Updates cookie, triggers re-render
#URL-Based LanguageFor /en/about, /fr/about patterns:
tsx
home = $page({  path: "/:lang/",  loader: async ({ params }) => {    // params.lang available for language selection  },});
#Lazy LoadingTranslations load on demand. Only the current language bundle is fetched.
typescript
en = $dictionary({  lazy: () => import("./translations/en.ts"),});
When switching languages:
Request new translation bundle
Wait for load
Re-render with new strings
No flash of untranslated content.
#Type SafetyThe tr function is fully typed. Invalid keys are compile-time errors:
tsx
// Given dictionary with "welcome", "greeting"tr("welcome")    // ✓ Validtr("welcom")     // ✗ Type error: typotr("missing")    // ✗ Type error: key doesn't exist
Placeholder types are inferred too:
tsx
// greeting: "Hello, {name}!"tr("greeting", { name: "Bob" })  // ✓ Validtr("greeting", { user: "Bob" })  // ✗ Type error: wrong placeholdertr("greeting")                   // ✗ Type error: missing placeholder
#Common Patterns
#Global Language ContextWrap your app to provide language context:
tsx
// AppLayout.tsxconst AppLayout = ({ children }) => {  const { lang } = useI18n<AppRouter, "en">();   // Set HTML lang attribute  useEffect(() => {    document.documentElement.lang = lang;  }, [lang]);   return <div>{children}</div>;};
#Language Switcher Componenttsx
const LanguageSwitcher = () => {  const { lang, setLang } = useI18n<AppRouter, "en">();   const languages = [    { code: "en", label: "English", flag: "🇺🇸" },    { code: "fr", label: "Français", flag: "🇫🇷" },    { code: "de", label: "Deutsch", flag: "🇩🇪" },  ];   return (    <div className="lang-switcher">      {languages.map((l) => (        <button          key={l.code}          onClick={() => setLang(l.code)}          className={lang === l.code ? "active" : ""}        >          {l.flag} {l.label}        </button>      ))}    </div>  );};
#Translating Outside ComponentsFor utility functions or services:
typescript
import { Alepha, $inject } from "alepha"; class NotificationService {  alepha = $inject(Alepha);   notify(key: string, params?: object) {    const tr = this.alepha.i18n.tr;    const message = tr(key, params);    // Send notification with translated message  }}
#RTL SupportDetect right-to-left languages:
tsx
const { lang } = useI18n<AppRouter, "en">();const isRTL = ["ar", "he", "fa"].includes(lang); return <div dir={isRTL ? "rtl" : "ltr"}>{children}</div>;
#Project StructureOrganize translations by feature or flat:

    bash
    
  
src/
├── translations/
│   ├── en.ts        # Flat structure
│   ├── fr.ts
│   └── de.ts
Or by feature:

    bash
    
  
src/
├── translations/
│   ├── en/
│   │   ├── common.ts
│   │   ├── auth.ts
│   │   └── dashboard.ts
│   ├── fr/
│   │   ├── common.ts
│   │   ├── auth.ts
│   │   └── dashboard.ts
Then merge in your main translation file:
typescript
// translations/en.tsimport common from "./en/common";import auth from "./en/auth";import dashboard from "./en/dashboard"; export default {  ...common,  auth,  dashboard,};
#Quick Referencetypescript
// Define dictionariesen = $dictionary({ lazy: () => import("./translations/en.ts") });fr = $dictionary({ lazy: () => import("./translations/fr.ts") }); // Use in componentsconst { tr, lang, setLang, l } = useI18n<AppRouter, "en">(); // Translatetr("key")tr("key", { placeholder: value })tr("nested.key") // Localizel(date, { date: "short" })l(number, { number: "decimal" })l(amount, { currency: "USD" }) // Switch languagesetLang("fr")
Previous: Forms | Back to: React Integration
On This Page
No headings found...

ready
│main│TypeScript
│UTF-8│guides_frontend_i18n.md│

#Internationalization (i18n)

#Setup

#Define Dictionaries

#Translation Files

#Using Translations

#The `useI18n` Hook

#What `useI18n` Returns

#Translation Function (`tr`)

#Simple Translations

#With Placeholders

#Pluralization

#Fallbacks

#Localization Helper (`l`)

#Language Detection

#Server-Side

#Client-Side

#URL-Based Language

#Lazy Loading

#Type Safety

#Common Patterns

#Global Language Context

#Language Switcher Component

#Translating Outside Components

#RTL Support

#Project Structure

#Quick Reference