or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-translation.mdindex.mdinitialization.mdjquery-integration.mdlanguage-management.mdresource-management.md
tile.json

core-translation.mddocs/

Core Translation

Core translation functionality providing the main translation methods with support for interpolation, pluralization, and contextual translations.

Capabilities

Translation Function

The main translation function that converts translation keys to localized strings with support for variables, plurals, and context.

/**
 * Translate a key to localized string
 * @param key - Translation key or array of keys
 * @param options - Translation options including variables and settings
 * @returns Translated string
 */
function t(key, options): string;
function translate(key, options): string; // Alias for t()

Usage Examples:

// Basic translation
i18n.t('welcome'); // "Welcome"

// Translation with interpolation
i18n.t('greeting', { name: 'John' }); // "Hello John"

// Pluralization
i18n.t('item', { count: 0 }); // "no items"
i18n.t('item', { count: 1 }); // "one item" 
i18n.t('item', { count: 5 }); // "5 items"

// Contextual translation
i18n.t('friend', { context: 'male' }); // "male friend"
i18n.t('friend', { context: 'female' }); // "female friend"

// Namespace-specific translation
i18n.t('common:button.save'); // "Save"

// Fallback keys
i18n.t(['error.specific', 'error.generic']); // Uses first available key

// With default value
i18n.t('missing.key', { defaultValue: 'Default text' }); // "Default text"

// Language override
i18n.t('greeting', { lng: 'es', name: 'Juan' }); // "Hola Juan"

// Nested object access
i18n.t('user.profile.title'); // "User Profile"

// Return nested objects
i18n.t('user', { returnObjectTrees: true }); // { profile: { title: "User Profile" } }

Exists Check

Checks if a translation key exists in the current language or fallback languages.

/**
 * Check if a translation key exists
 * @param key - Translation key to check
 * @param options - Check options including language override
 * @returns True if key exists, false otherwise
 */
function exists(key, options): boolean;

Usage Examples:

// Check if key exists
if (i18n.exists('welcome')) {
  console.log(i18n.t('welcome'));
}

// Check with language override
if (i18n.exists('greeting', { lng: 'es' })) {
  console.log(i18n.t('greeting', { lng: 'es' }));
}

// Check namespaced key
if (i18n.exists('common:button.save')) {
  console.log(i18n.t('common:button.save'));
}

Advanced Features

Variable Interpolation

Variables are replaced using the configured interpolation prefix and suffix (default: 

__variable__
).

// Translation resource: "Hello __name__, you have __count__ messages"
i18n.t('messages', { 
  name: 'Alice', 
  count: 5 
}); // "Hello Alice, you have 5 messages"

// HTML escaping (controlled by escapeInterpolation option)
i18n.t('html', { 
  content: '<script>alert("xss")</script>' 
}); // Content is escaped by default

// Unescaped HTML (use with caution)
i18n.t('html', { 
  contentHTML: '<b>Bold text</b>' 
}); // HTML is not escaped when using HTML suffix

Nested Key Access

Access nested translation objects using the key separator (default: 

.
).

// Translation resource structure:
// {
//   "user": {
//     "profile": {
//       "title": "User Profile",
//       "description": "Manage your account settings"
//     }
//   }
// }

i18n.t('user.profile.title'); // "User Profile"
i18n.t('user.profile.description'); // "Manage your account settings"

Pluralization Rules

Automatic plural form selection based on count value and language-specific rules.

// English pluralization
i18n.t('item', { count: 0 }); // "no items" (uses item_plural_0 or item_zero)
i18n.t('item', { count: 1 }); // "one item" (uses item)
i18n.t('item', { count: 2 }); // "2 items" (uses item_plural)

// Complex pluralization (e.g., Russian with multiple plural forms)
i18n.t('item', { count: 1, lng: 'ru' }); // "1 предмет"
i18n.t('item', { count: 2, lng: 'ru' }); // "2 предмета"
i18n.t('item', { count: 5, lng: 'ru' }); // "5 предметов"

Context Handling

Contextual translations based on conditions or user attributes.

// Translation resources:
// "friend": "friend",
// "friend_male": "boyfriend", 
// "friend_female": "girlfriend"

i18n.t('friend'); // "friend"
i18n.t('friend', { context: 'male' }); // "boyfriend"
i18n.t('friend', { context: 'female' }); // "girlfriend"

Reuse and Nesting

Reference other translation keys within translations using 

$t(key)
syntax.

// Translation resources:
// "greeting": "Hello",
// "welcome": "$t(greeting) and welcome to our app!"

i18n.t('welcome'); // "Hello and welcome to our app!"

// With parameters
// "user_greeting": "$t(greeting, {\"name\": \"__name__\"})"
i18n.t('user_greeting', { name: 'John' }); // "Hello John"

Error Handling

// Missing key handling
i18n.t('missing.key'); // Returns the key itself: "missing.key"

// With default value
i18n.t('missing.key', { defaultValue: 'Fallback text' }); // "Fallback text"

// Empty translation handling (controlled by fallbackOnEmpty option)
i18n.t('empty.translation'); // May return empty string or fallback

// Null value handling (controlled by fallbackOnNull option)  
i18n.t('null.translation'); // May return null or fallback