Translations

A translation registry for storing localized text keys and resolving plural-aware output.

Import

import { Translations } from "@schukai/monster/source/i18n/translations.mjs";

Source

View source code

Package

@schukai/monster

Since

1.13.0

Introduction

Translations stores localized strings and provides lookups by key. It supports plural rules based on the active locale.

Core Responsibilities

Surface	What it solves
`setText()`	Stores a single text entry or a plural rule object under one key.
`assignTranslations()`	Loads a whole translation map in one step.
`getText()`	Returns a scalar text value and supports explicit fallback text.
`getPluralRuleText()`	Resolves plural-aware output for numbers or explicit plural keywords.

Basic Usage


import { Translations } from "@schukai/monster/source/i18n/translations.mjs";

const translations = new Translations("en");
translations.setText("welcome", "Welcome back");

translations.getText("welcome");

Plural Rules


translations.setText("files", {
    zero: "No files",
    one: "One file",
    other: "{count} files"
});

translations.getPluralRuleText("files", 3, "Files");

Bulk Assignment

Use assignTranslations() to load multiple keys at once from a plain object.

Why It Matters

Translations is the stable registry that providers, custom elements and renderers can all share. It keeps the lookup rules in one place instead of pushing locale conditionals into every component.

Resolve Singular And Plural Translations

import { Locale } from "@schukai/monster/source/i18n/locale.mjs";
import { Translations } from "@schukai/monster/source/i18n/translations.mjs";

const output = document.getElementById("translations-output");
const translations = new Translations(new Locale("en", "US"));

translations.setText("headline", "Items in cart");
translations.setText("count", {
    one: "1 item",
    other: "{{count}} items",
});

document.getElementById("translations-run").addEventListener("click", () => {
    output.textContent = JSON.stringify(
        {
            headline: translations.getText("headline"),
            one: translations.getPluralRuleText("count", 1),
            many: translations.getPluralRuleText("count", 4).replace("{{count}}", "4"),
        },
        null,
        2,
    );
});

Open in playground

Load Multiple Translation Keys From Plain Objects

import { Translations } from "@schukai/monster/source/i18n/translations.mjs";

const translations = new Translations("en");

document.getElementById("translations-bulk-run").addEventListener("click", () => {
    translations.assignTranslations({
        title: "Documentation",
        state: {
            one: "1 change",
            other: "{count} changes",
        },
        owner: "Core team",
    });

    document.getElementById("translations-bulk-output").textContent = JSON.stringify({
        title: translations.getText("title"),
        one: translations.getPluralRuleText("state", 1, "").replace("{count}", "1"),
        many: translations.getPluralRuleText("state", 6, "").replace("{count}", "6"),
        owner: translations.getText("owner"),
    }, null, 2);
});

Open in playground

Use Explicit Default Text When A Key Is Missing

import { Translations } from "@schukai/monster/source/i18n/translations.mjs";

const translations = new Translations("en");
translations.setText("ready", "Ready");

document.getElementById("translations-fallback-run").addEventListener("click", () => {
    document.getElementById("translations-fallback-output").textContent = JSON.stringify({
        existing: translations.getText("ready", "Fallback"),
        missing: translations.getText("missing-key", "Fallback text"),
        pluralMissing: translations.getPluralRuleText("missing-count", 4, "4 items"),
    }, null, 2);
});

Open in playground

Resolve Plural Texts With Explicit Plural Rule Keywords

import { Translations } from "@schukai/monster/source/i18n/translations.mjs";

const translations = new Translations("en");
translations.setText("downloads", {
    zero: "No downloads yet",
    one: "One download",
    other: "{count} downloads",
});

document.getElementById("translations-keywords-run").addEventListener("click", () => {
    document.getElementById("translations-keywords-output").textContent = JSON.stringify({
        zero: translations.getPluralRuleText("downloads", "zero", ""),
        one: translations.getPluralRuleText("downloads", "one", ""),
        other: translations.getPluralRuleText("downloads", "other", "{count} downloads"),
    }, null, 2);
});

Open in playground

Exported

Translations, getDocumentTranslations

Derived from

Base

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the Base.

Option

Type

Default

Description

-/-

Properties

The Properties listed in this section are defined directly within the class. This class is derived from several parent classes. Therefore, it inherits Properties from these parent classes. If you cannot find a specific Properties in this list, we recommend consulting the documentation of the Base.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the Base.

Constructor

constructor(locale)

Parameters

locale {locale}: locale

Structural methods

getPluralRuleText(key,count,defaultText)

Parameters

key {string}: key
count {integer|string}: count
defaultText {string|undefined}: defaultText

Returns

{string}

A number count can be passed to this method. In addition to a number, one of the keywords can also be passed directly. "zero", "one", "two", "few", "many" and "other". Remember: not every language has all rules. The appropriate text for this number is then selected. If no suitable key is found, defaultText is taken.

getText(key,defaultText)

Parameters

key {string}: key
defaultText {string|undefined}: defaultText

Returns

{string}

Throws

{Error} key not found

Fetches a text using the specified key. If no suitable key is found, defaultText is taken.

setText(key,text)

Parameters

key {string}: key
text {string|object}: text

Returns

{Translations}

Throws

{TypeError} value is not a string or object

Set a text for a key ``

translations.setText("text1", "Make my day!"); // plural rules translations.setText("text6", { "zero": "There are no files on Disk.", "one": "There is one file on Disk.", "other": "There are files on Disk." "default": "There are files on Disk." });

Static methods

[instanceSymbol]()3.27.0

Returns

{symbol}

This method is called by the instanceof operator.

Other methods

assignTranslations(translations)

Parameters

translations {object}: translations

Returns

{Translations}

This method can be used to transfer overlays from an object. The keys are transferred, and the values are entered as text. The values can either be character strings or, in the case of texts with plural forms, objects. The plural forms must be stored as text via a standard key "zero", "one", "two", "few", "many" and "other". Additionally, the key default can be specified, which will be used if no other key fits. In some languages, like for example in German, there is no own more number at the value 0. In these languages, the function applies additionally zero. ``

translations.assignTranslations({ "text1": "Make my day!", "text2": "I'll be back!", "text6": { "zero": "There are no files on Disk.", "one": "There is one file on Disk.", "other": "There are files on Disk." "default": "There are files on Disk." });

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.