@sphinxjs/label

Translates and normalises Label values, the bridge between your data model and displayed text.

Why this package exists

Many UI components need to display a name for something: a collection title, a field label, an action button. That name might be:

• A hardcoded string, "Employees"
• A translated string, looked up from a .po catalog at render time
• Derived from a key, "paymentRequest" → "Payment Requests"

Instead of handling each case at every call site, you declare a Label type on your props and let normaliseLabel resolve it to a plain string:

type Label = string | TranslationInformation;

interface CollectionConfig {
  label: Label;
  labelPlural?: Label;
}

Components and configs never deal with translation directly, they just hold a Label. Translation happens once, at the boundary where text meets the UI.

Install

pnpm add @sphinxjs/label

Usage

translateLabel(label, options?)

Resolves a Label to a translated string using the global Sphinx store. Plain strings pass through unchanged. TranslationInformation objects are looked up in the active locale's catalog.

import { translateLabel } from "@sphinxjs/label";

// Plain string, returned as-is
translateLabel("Employees");
// → "Employees"

// TranslationInformation, looked up in catalog
translateLabel({ msgid: "Employee" });
// → "Mitarbeiter"  (with German locale active)

// With plural form
translateLabel({ msgid: "Employee", plural: "Employees" }, { count: 3 });
// → "Mitarbeiter"  (singular) or "Mitarbeiter" (plural, translated)

normaliseLabel(label?, options?)

Like translateLabel but handles three additional cases:

• undefined label with a fallbackKey, converts a camelCase or snake_case key to a human-readable string
• singular: true / plural: true, coerces the result through pluralize regardless of count
• undefined with no fallback, returns undefined

import { normaliseLabel } from "@sphinxjs/label";

// Translate a TranslationInformation and force plural form
normaliseLabel({ msgid: "Invoice" }, { plural: true });
// → "Invoices"  (translated + pluralised)

// Humanise a config key when no label is defined
normaliseLabel(undefined, { fallbackKey: "paymentRequest", plural: true });
// → "Payment Requests"

// Plain string, forced to singular
normaliseLabel("Employees", { singular: true });
// → "Employee"

This is particularly useful in generic components that receive a config object, they can display a reasonable label even when the author didn't explicitly set one.

Options

| Option | Type | Description | | ------------- | --------- | -------------------------------------------------------------- | | count | number | Selects plural form during catalog lookup (default 1) | | plural | boolean | Force plural form via pluralize after translation | | singular | boolean | Force singular form via pluralize after translation | | fallbackKey | string | camelCase/snake_case key to humanise when label is undefined |

TranslationInformation builders

These functions construct TranslationInformation objects that can be stored in config and resolved later by translateLabel / normaliseLabel. They mirror the standard gettext API but return objects instead of strings.

import { gettext, ngettext, pgettext, dgettext } from "@sphinxjs/label";

const config = {
  label: gettext("Invoice"),
  labelPlural: ngettext("Invoice", "Invoices"),
  // With context
  action: pgettext("button", "Save"),
  // From a specific domain
  status: dgettext("billing", "Paid"),
};

Advanced: unbound variants

unboundTranslateLabel and unboundNormaliseLabel accept a SphinxGetter as their first argument. Use these when you need to translate against a specific Sphinx instance rather than the global store, for example in tests, server-side rendering with per-request instances, or domain-scoped hooks.

import { unboundTranslateLabel } from "@sphinxjs/label";

unboundTranslateLabel(mySphinxGetter, { msgid: "Invoice" });