Trin

Description

Trin is a compile-time and runtime-safe internationalization (i18n) engine designed for TypeScript applications. It enables structured, type-safe translation management with support for dynamic logic, nested key validation, conditional rendering, pluralization, switch-case logic, and modifier pipelines. Trin ensures that translation keys, argument values, and transformation syntax are validated at compile time where possible, dramatically reducing the risk of runtime errors. It also supports runtime locale switching, safe fallback mechanisms, and custom embedded logic using regular expressions, all while having zero dependencies.

Goals

Validate translation keys and arguments at compile time to ensure correctness.
Minimize runtime translation errors with structured syntax and logic support.

Features

Type-safe translation keys: Ensures only valid keys are used through deep object traversal and TypeScript inference.
Dynamic argument substitution: Allows transformations like {{ name | capitalize }} at runtime using safe substitution pipelines.
Conditional expressions: Supports ternary logic in strings, e.g., {{ ?.isAdmin ? 'Admin' : 'User' }}.
Pluralization: Handles pluralization with syntax like [plural.key].
Switch-case logic: Use key-value logic to resolve strings, e.g., {{ !.role k:'admin' v:'Admin' }}.
Modifier pipelines: Supports string modifiers like uppercase, lowercase, and capitalize in sequence.
Locale management: Provides runtime validation and switching of active locales.

Usage

import { createTranslation } from '@smaiill/trin'

// Example 1: Basic placeholder with capitalize filter
const { t } = createTranslation(
  {
    en: {
      greeting: 'Hello, {{ name | capitalize }}.',
    },
  },
  {
    locale: 'en',
  },
)

t('greeting', { name: 'john' })
// Output: Hello, John.

import { createTranslation } from '@smaiill/trin'

// Example 2: Ternary conditional rendering
const { t } = createTranslation(
  {
    en: {
      status: "{{ ?.isLoggedIn ? 'Welcome back' : 'Please log in' }}",
    },
  },
  {
    locale: 'en',
  },
)

t('status', { isLoggedIn: false })
// Output: Please log in

t('status', { isLoggedIn: true })
// Output: Welcome back

import { createTranslation } from '@smaiill/trin'

// Example 3: Pluralization with item count
const { t } = createTranslation(
  {
    en: {
      itemCount: 'You have {{ itemCount }} item[plural.itemCount].',
    },
  },
  {
    locale: 'en',
  },
)

t('itemCount', { itemCount: 1 })
// Output: You have 1 item.

t('itemCount', { itemCount: 3 })
// Output: You have 3 items.

import { createTranslation } from '@smaiill/trin'

// Example 4: Role-based view with key-value matching
const { t } = createTranslation(
  {
    en: {
      roleView: '{{ !.role k:"admin" v:"Admin Panel" k:"user" v:"User Dashboard" }}',
    },
  },
  {
    locale: 'en',
  },
)

t('roleView', { role: 'admin' })
// Output: Admin Panel

t('roleView', { role: 'user' })
// Output: User Dashboard

Learning outcomes

DSL-style syntax parsing inside strings
Compile-time validation mechanisms in TypeScript
Robust i18n infrastructure with dynamic logic support
Fallback handling and argument safety in translations