Translation

The @talosjs/translation component is an internationalization layer for multi-language applications. You extend the Translation base class, point it at a dictionary, and resolve localized strings with trans(key, options), which handles dot-notation keys, {{ param }} interpolation, and count-driven pluralization. The dictionary is keyed by locale, with en as the always-present fallback, across 31 supported locale codes.

How lookups resolve

One dictionary covers every locale: each leaf carries its translations keyed by locale code (en, fr, es, …), and en is the guaranteed fallback when a target locale is missing. You reach nested entries with dot-notation keys like trans("user.profile.name"), however deep the dictionary nests. {{ param }} placeholders are filled through params, so there’s no string concatenation, and pluralization picks the right sibling key (<key>, <key>_plural, <key>_zero) from the count you pass. Register a translation class with a decorator and resolve it from the container.

How it works

You extend Translation and implement two methods: getName() returns a stable identifier for the domain, and getDict() returns the dictionary. Lookups go through has() and trans(), which resolve the requested locale, fall back to en, interpolate, and pick the right plural form.

Member	Purpose
`trans(key, options?)`	Resolve a localized string for `key`; interpolates `params` and selects the plural form from `count`.
`has(key)`	Whether `key` exists in the dictionary.
`getName()`	Abstract — a stable identifier for the translation domain.
`getDict()`	Abstract — returns the `TranslationDictType` dictionary.

trans() accepts a TransOptionsType:

Option	Type	Purpose
`lang`	`LocaleType`	Target locale. Defaults to `en`.
`params`	`TransParamsType`	Values for `{{ param }}` placeholders.
`count`	`number`	Selects the pluralization sibling (singular / `_plural` / `_zero`).

Resolution order: the requested lang is tried first, then the en fallback. A missing key throws with KEY_NOT_FOUND; a key present but absent in both the locale and the en fallback throws with LOCALE_NOT_FOUND. Pluralization picks <key> when count === 1, <key>_plural when count > 1 or count < 0, and <key>_zero when count === 0 (falling back to _plural if _zero is absent). The supported locale codes are exported as locales:

ar bg cs da de el en eo es et eu fi fr hu hy it ja ko lt nl no pl pt ro ru sk sv th uk zh zh-tw

Usage

Extend Translation, load a dictionary, and resolve keys through trans().

import type { TranslationDictType } from "@talosjs/translation";
import { decorator, Translation } from "@talosjs/translation";
import dict from "./translations.yml";

@decorator.translation()
export class CheckoutTranslation extends Translation {
  public getName = (): string => "checkout";

  public getDict = (): TranslationDictType => dict as TranslationDictType;
}

Resolve it from the container and translate keys:

import { container } from "@talosjs/container";

const t = container.get(CheckoutTranslation);

// Simple lookup with fallback to "en"
t.trans("user.profile.name", { lang: "fr" }); // "Nom complet"

// Interpolation with params
t.trans("coach.session.welcome", { lang: "fr", params: { name: "Marie" } });
// "Bon retour, Marie !"

// Pluralization driven by count
t.trans("cart.items", { count: 0 }); // "No items"   (items_zero)
t.trans("cart.items", { count: 1 }); // "1 item"     (items)
t.trans("cart.items", { count: 5 }); // "5 items"    (items_plural)

// Existence check
t.has("user.profile.email"); // true

The dictionary is a tree of nested keys; each leaf is an object keyed by locale code. Interpolation uses {{ param }} placeholders, and pluralization uses sibling keys selected by count:

# translations.yml
user:
  profile:
    name:
      en: "Full name"
      fr: "Nom complet"

coach:
  session:
    welcome:
      en: "Welcome back, {{ name }}!"
      fr: "Bon retour, {{ name }} !"

cart:
  items:
    en: "{{ count }} item"
    fr: "{{ count }} article"
  items_plural:
    en: "{{ count }} items"
    fr: "{{ count }} articles"
  items_zero:
    en: "No items"
    fr: "Aucun article"

Exceptions

The component throws TranslationException when a key cannot be resolved. It carries a machine-readable key, a human-readable message, and a data object (with the lookup key and lang).

Key	When
`KEY_NOT_FOUND`	The requested key does not exist in the dictionary.
`LOCALE_NOT_FOUND`	The key exists but has no value for the requested locale or the `en` fallback.

import { TranslationException } from "@talosjs/translation";

try {
  return t.trans("user.profile.name", { lang: "fr" });
} catch (error) {
  if (error instanceof TranslationException) {
    logger.error(`Translation error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Keeping dictionaries reliable

Always provide an en value, since it’s the fallback for every locale; a key without one throws LOCALE_NOT_FOUND whenever the target locale is missing. Group keys by domain along stable dot-notation paths like user.profile.name so dictionaries stay navigable and getName() maps cleanly to a domain. Keep placeholders verbatim: {{ name }} and {{ count }} have to appear identically across locales, with only the surrounding words changing. For pluralized keys, pass count and provide the <key>, <key>_plural, and optionally <key>_zero siblings so the correct form is selected. Translate meaning rather than words, phrasing each string the way a native speaker writing the product UI would and following the locale’s capitalization and punctuation conventions. When you complete locales, fill blanks only; keep keys stable and existing entries intact.

CLI command

Scaffold a translation class, its test file, and a sibling translations.yml dictionary with the generator. It writes the class under modules/<module>/src/translations/<Name>Translation.ts and installs @talosjs/translation if it is missing.

# Interactive: prompts for the name
talos translation:create

# Provide the name
talos translation:create --name=Checkout

# Target a module and overwrite
talos translation:create --name=Checkout --module=shop --override

Option	Description	Default
`--name`	Translation class name. The `Translation` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class extends Translation and loads the sibling translations.yml as its dictionary, ready for you to fill the keys:

import type { TranslationDictType } from "@talosjs/translation";
import { decorator, Translation } from "@talosjs/translation";
import dict from "./translations.yml";

@decorator.translation()
export class CheckoutTranslation extends Translation {
  public getName = (): string => "checkout";

  public getDict = (): TranslationDictType => dict as TranslationDictType;
}

The sibling translations.yml is written once per folder, so translation classes in the same translations/ directory share one dictionary. See translation:create for the full command reference.

Use with Claude and Codex

The generator ships matching translation:create and translation:translate skills. The first runs the scaffold and guides your AI agent through filling the dictionary; the second translates existing dictionaries meaning-for-meaning, completing every target locale from the en source. Initialize the skills once for your agent.

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the translations:

Prompt

Create translations for the checkout page in English and French.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generator, runs it, and fills in the translations:

Prompt

Create translations for the checkout page in English and French.

For example, the prompt above maps to translation:create --name=Checkout, then fills the translations.yml dictionary with the en and fr entries for each key.

Getting Started

AI

Framework

Command Line

How lookups resolve

How it works

Usage

Exceptions

Keeping dictionaries reliable

CLI command

Use with Claude and Codex

​How lookups resolve

​How it works

​Usage

​Exceptions

​Keeping dictionaries reliable

​CLI command

​Use with Claude and Codex

How lookups resolve

How it works

Usage

Exceptions

Keeping dictionaries reliable

CLI command

Use with Claude and Codex