@onirix/i18n-module

v2.0.0

Published

2 months ago

Onirix helper for internationalization experiences.

Downloads

0High
0Medium
0Low

frangaren

vifergo

onirix_development

Augmented reality WebAR Industry i18n question checklist

Onirix I18n

Onirix I18n allows you to internationalize your experiences modifying labels text based on a language and a set of texts.

Simply add data sheets to Studio elements or provided an object with language information and Onirix I18n Module will take care of modifying the text when the scene is loaded.

Onirix I18n has several modes of operation depending on the data you pass to the constructor.

Since version v2.0.0.0 Onirix I18n also helps you to internationalize the text of the experience UI (html).

Internationalization of the AR experience labels

Using Onirix Studio data structures

If you haven't heard of data sheets and data structures in Onirix Studio, take a look at our documentation about the Datastore module.

In the Onirix Studio scene editor you can add data-sheets to the labels of your scene. These data-sheets must contain the texts that the label can have in the different languages. Each label will have its own data sheet and the Onirix i18n Module will choose the text in the appropriate language and display it on the label.

By default Onirix I18n used a data-structure called ox-i18n but you can pass diferent one indicating its name on the constructor. The structure defines the languages available for the experience.

To use a custom data-structure mode you must define one with a a list of input elements. The name of each input must be the ISO code of the language ('es', 'en', 'de', etc).

Using internationalization inline object.

You can pass a internationalization object with information about the label and the languages and texts that can be aplayed.

This object must be an array with one element for each label to be internationalised. Each element will have the oid of the label in the Onirix Studio scene and an i18n object with the text to display in each language.

[
    {
        "labelOid": "c6c4f5de-84c0-470a-b31e-a64e104afc23"
        "i18n": [
            {
                "es": "Spanish text"
            },
            {
                "en": "English text"
            }
        ]
    }
]

Internationalizing HTML Content

Body data attribute

When the internationalization module is instantiated, a new data attribute data-ox-i18-locale is automatically added to the document body. The value of this attribute will be the ISO code of the language used to call the module constructor.

<body data-ox-i18-locale="es">
    ...
</body>


/* Styles and resources specific to Spanish */
body[data-ox-i18-locale="es"] {
    background-color: #e0f7fa; /* Change background color */
    color: #00796b; /* Change text color */
}

body[data-ox-i18-locale="es"] .locale-image {
    content: url('image-es.jpg'); /* Change image based on language */
}

/* Styles and resources specific to English */
body[data-ox-i18-locale="en"] {
    background-color: #f3e5f5; /* Change background color */
    color: #6a1b9a; /* Change text color */
}

body[data-ox-i18-locale="en"] .locale-image {
    content: url('image-en.jpg'); /* Change image based on language */
}

HTML Structure

Each HTML element that need to be internationalized will have a data-ox-i18n attribute that acts as a key for identifying the text to display.

<h1 data-ox-i18n="your_key_title"></h1>
...
<p data-ox-i18n="your_key_1"></p>
...
<span data-ox-i18n="your_key_2"></span>

The internationalization inline object

The i18nUITexts array contains the internationalization data for each text element. Each object in the array includes an oxi18n key that matches the data-ox-i18n attribute in the HTML and an i18n array with translations for different languages.

The i18nUITexts array must be added to the constructor's parameters.

const i18nUITexts = [
    {
        oxi18n: "your_key_title",
        i18n: [
            { en: "This is the English title" },
            { es: 'Este es el título en Español' }
        ]
    },
    {
        oxi18n: "your_key_1",
        i18n: [
            { en: "In the bustling town of Cookieville, every Friday was a celebration of the beloved chocolate chip cookie. Bakers from all around would gather in the town square, each claiming their recipe was the best. It wasn't just about the cookies, though; it was the laughter, the shared stories, and the joy of crumbs on everyone's faces that made the day truly special." },
            { es: 'En el bullicioso pueblo de Galletilandia, cada viernes era una celebración de la querida galleta con chispas de chocolate. Panaderos de todos lados se reunían en la plaza del pueblo, cada uno afirmando que su receta era la mejor. Pero no se trataba solo de las galletas; era la risa, las historias compartidas y la alegría de las migas en las caras de todos lo que hacía el día verdaderamente especial.' }
        ]
    },
    {
        oxi18n: "your_key_2",
        i18n: [
            { en: "a curious cat named Whiskers" },
            { es: "un curioso gato llamado Bigotes" }
        ]
    },
];

const oxI18n = new OnirixI18nModule(embedSDK, "es", { i18nUITexts: i18nUITexts });

Install

npm install @onirix/i18n-module

Include the dependency within the HTML head tag:

<head>
    <script src="https://unpkg.com/@onirix/[email protected]/dist/ox-i18n-module.umd.js"/>
</head>

As ESM modules:

import OnirixI18nModule from "https://unpkg.com/@onirix/[email protected]/dist/ox-i18n-module.esm.js";

Usage

To use this library, first, the EmbedSDK must be initialize and pass it to the constructor. Next, you must provide the language that the module will use.

import OnirixEmbedSDK from "https://unpkg.com/@onirix/[email protected]/dist/ox-embed-sdk.esm.js";
import OnirixI18nModule from "https://unpkg.com/@onirix/[email protected]/dist/ox-i18n-module.esm.js";

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const oxI18n = new OnirixI18nModule(embedSDK, "en");

If you want to use the language of the user's browser, you can use this:

import OnirixEmbedSDK from "https://unpkg.com/@onirix/[email protected]/dist/ox-embed-sdk.esm.js";
import OnirixI18nModule from "https://unpkg.com/@onirix/[email protected]/dist/ox-i18n-module.esm.js";

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const oxI18n = new OnirixI18nModule(embedSDK, navigator.language || navigator.userLanguage);

If the selected language is not among the available languages (specified in the template), the first language defined in the template will be used.

Additionally, a third parameter must be reported that must contain certain information.

import OnirixEmbedSDK from "https://unpkg.com/@onirix/[email protected]/dist/ox-embed-sdk.esm.js";
import OnirixI18nModule from "https://unpkg.com/@onirix/[email protected]/dist/ox-i18n-module.esm.js";

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const language ="es";

const params = {
    template: "custom-data-structure-name",
    i18nLabelsTexts: null ,
    i18nUITexts: null
};

const oxI18n = new OnirixI18nModule(embedSDK, language, params);

The template parameter allows you to indicate to Onirix I18n the data structure it will find in your experience. By default the value is ox-i18n.

The i18nLabelsTexts is an array that contains information about the labels, the languages that each of them can have and also the text that corresponds to each language.

const i18nLabelsTexts = [
    {
        labelOid: string;
        i18n: [
            {
                es: "Spanish text"
            },
            {
                en: "English text"
            }
        ]
    }
]

The i18nUITexts is an array that contains information about the key of HTML elements, the languages that each of them can have and also the text that corresponds to each language.

const i18nUITexts = [
    {
        oxi18n: string,
        i18n: [
            {
                es: "Spanish text"
            },
            {
                en: "English text"
            }
        ]
    }
];