18. Translations.md

Translations

Introduction

When building components, templates or UI, you often want to mark labels with a translation value.

crsbinding allows you to:

1. add translations with or without a context
2. remove a translation context
3. get a translation value
4. express translations in the UI

Adding translations

This structure will be used in the rest of the documentation as examples.

const trans = {
    title: "Translation Title",
    buttons: {
        save: "Save",
        cancel: "Cancel"
    }
}

crsbinding.translations.add(trans);
crsbinding.translations.add(trans, "context");

The first parameter is the translation object you want to register. The second is a defined context so that you can define translations for a part of your UI that is temp. The object structure will be flattened so that you can define it in a path express.

<div>&{buttons.save}</div>

or

crsbinding.translations.get("button.save");

Remove context

await crsbinding.translations.delete("context");

All translations that was added using the context ("context") will be removed from the translations dictionary. If you want to use it again later you will need to add it again using the add function.

Get value

There are times when you want to get the translation value using code.

const value = crsbinding.translations.get("button.save");

If the value is defined on the translations dictionary it will return you the value, in this case the value "Save". If however the value is not defined on the dictionary it will return null.

In some cases you may want to have a more dynamic structure where you load items on demand and store them. In those cases you want to hook a async function called fetch on the translations object.

crsbinding.translations.fetch = async (key) => {//... fetch the value and return it for this key}

This may cause performance issues depending on how you take to fetch the appropriate value from your storage.

Marking translations in the HTML

crsbinding.translations.add({
    title: "Hello World Title",
    value: "Hello World Value"
})

<div data-title="&{title}">&{value}</div>

When the UI is parsed the value of "title" ("Hello World Title") will be the attribute value of data-title. The textContent of the div will be the value of the "value" translation key ("Hello World Value").

When ever elements are parsed the translations is checked and the element and attribute values updated.

Custom components

If you are writing a component that is not using BindableElement or PerspectiveElement you will need to make sure you parse the element for translations.

class Component extends HTMLElement {
    async connectedCallback() {
        this.innerHTML = await fetch(import.meta.url.replace(".js", ".html")).then(result => result.text());
        await crsbinding.translations.parseElement(this);
    }
}

customElements.define("component-element", Component);

If you have timing issues between the screen parsing and the translations being available, you can use the same above function to recheck the translations once they are available.