Angular Embedded AnalyticsLocalisation

Version 3.1.1

The displayed text in Studio can be customised for localisation by providing locale information in the required language.

Use the localeText property to apply one of the provided locales or create a custom one, or the getLocaleText callback to integrate Studio with your application's localisation system.

localeTextCopy Link
AgStudioLocaleText
A map of key->value pairs for localising text within Studio.
getLocaleTextCopy Link
Function
A callback for localising text within Studio.

Provided Locales Copy Link

The default language of Studio is American English, however, we provide a number of translations that can be used as a starting point for commonly requested languages:

LanguageBCP47 TagLocale Module
Arabic (Egyptian)ar-EGAG_STUDIO_LOCALE_AR_EG
Bengali (Bangladesh)bn-BDAG_STUDIO_LOCALE_BN_BD
Bengali (India)bn-INAG_STUDIO_LOCALE_BN_IN
Bosnianbs-BAAG_STUDIO_LOCALE_BS_BA
Bulgarianbg-BGAG_STUDIO_LOCALE_BG_BG
Chinese (Traditional)zh-HKAG_STUDIO_LOCALE_ZH_HK
Chinese (Simplified)zh-CNAG_STUDIO_LOCALE_ZH_CN
Chinese (Taiwan)zh-TWAG_STUDIO_LOCALE_ZH_TW
Croatianhr-HRAG_STUDIO_LOCALE_HR_HR
Czechcs-CZAG_STUDIO_LOCALE_CS_CZ
Danishda-DKAG_STUDIO_LOCALE_DA_DK
Dutchnl-NLAG_STUDIO_LOCALE_NL_NL
Estonianet-EEAG_STUDIO_LOCALE_ET_EE
Filipinofil-PHAG_STUDIO_LOCALE_FIL_PH
Finnishfi-FIAG_STUDIO_LOCALE_FI_FI
Frenchfr-FRAG_STUDIO_LOCALE_FR_FR
Germande-DEAG_STUDIO_LOCALE_DE_DE
Greekel-GRAG_STUDIO_LOCALE_EL_GR
Hebrewhe-ILAG_STUDIO_LOCALE_HE_IL
Hindihi-INAG_STUDIO_LOCALE_HI_IN
Hungarianhu-HUAG_STUDIO_LOCALE_HU_HU
Indonesianid-IDAG_STUDIO_LOCALE_ID_ID
Italianit-ITAG_STUDIO_LOCALE_IT_IT
Japaneseja-JPAG_STUDIO_LOCALE_JA_JP
Koreanko-KRAG_STUDIO_LOCALE_KO_KR
Latvianlv-LVAG_STUDIO_LOCALE_LV_LV
Lithuanianlt-LTAG_STUDIO_LOCALE_LT_LT
Malayms-MYAG_STUDIO_LOCALE_MS_MY
Norwegian (Bokmål)nb-NOAG_STUDIO_LOCALE_NB_NO
Persianfa-IRAG_STUDIO_LOCALE_FA_IR
Polishpl-PLAG_STUDIO_LOCALE_PL_PL
Portuguesept-PTAG_STUDIO_LOCALE_PT_PT
Portuguese (Brazil)pt-BRAG_STUDIO_LOCALE_PT_BR
Romanianro-ROAG_STUDIO_LOCALE_RO_RO
Russianru-RUAG_STUDIO_LOCALE_RU_RU
Serbian (Cyrillic)sr-RSAG_STUDIO_LOCALE_SR_RS
Serbian (Latin)sr-Latn-RSAG_STUDIO_LOCALE_SR_LATN_RS
Slovaksk-SKAG_STUDIO_LOCALE_SK_SK
Sloveniansl-SIAG_STUDIO_LOCALE_SL_SI
Spanishes-ESAG_STUDIO_LOCALE_ES_ES
Swedishsv-SEAG_STUDIO_LOCALE_SV_SE
Thaith-THAG_STUDIO_LOCALE_TH_TH
Turkishtr-TRAG_STUDIO_LOCALE_TR_TR
Ukrainianuk-UAAG_STUDIO_LOCALE_UK_UA
Urdu (Pakistan)ur-PKAG_STUDIO_LOCALE_UR_PK
Vietnamesevi-VNAG_STUDIO_LOCALE_VI_VN

Translations are provided as an illustration only and are not guaranteed to be accurate or error free. They are designed to show developers where to store their chosen phrase or spelling variant in the target language.

Using a Provided Locale Copy Link

All of the provided locales listed above are available in the ag-studio-locale package. To use any of the provided locales in your application, follow these steps:

First, import the desired locale module from the ag-studio-locale package. For example, to use the German locale, import AG_STUDIO_LOCALE_DE_DE:

import { AG_STUDIO_LOCALE_DE_DE } from 'ag-studio-locale';

Next, assign the imported locale object to the localeText property in your Studio properties:

<ag-studio
    [localeText]="localeText"
    /* other studio properties ... */ />

this.localeText = AG_STUDIO_LOCALE_DE_DE;

Finally, ensure the ag-studio-locale module is listed as a dependency in your application's package configuration:

"dependencies": {
    "ag-studio-locale": "3.1.1",
    ...
}

The following example demonstrates applying the AG_STUDIO_LOCALE_DE_DE locale to Studio:

Some localisation variables have ${variable} in them. When this occurs, it means that part of the string will be replaced by a variable value.

Customising a Provided Locale Copy Link

If you want to customise a provided locale, you can do so by creating a new object and merging the provided locale with your customisations.

import { AG_STUDIO_LOCALE_DE_DE } from 'ag-studio-locale';

const customGermanLocale = {
    ...AG_STUDIO_LOCALE_DE_DE,
    // customise the locale here
};

const studioProperties = {
    localeText: customGermanLocale,
};

The example below shows this in action by adding a "zzz-" prefix to each Locale value to create a new ZZZ_LOCALE object, and then applying this customised locale to Studio:

Custom Locales Copy Link

By default, Studio does not require a locale. If no locale is provided, Studio will default to English. If a locale is provided but is missing values, the default English will be used for the missing values.

To create a new locale, translate based off of one of the provided locales in ag-studio-locale (it is recommended to use AG_STUDIO_LOCALE_EN_US).

Locale Callback Copy Link

Providing a locale for Studio may not fit in with localisation libraries or localisation for a broader application. If you want Studio to take from an application-wide locale, then implement the getLocaleText callback to act as a bridge between Studio and the application's localisation.

The example below shows providing a callback for localisation. The example for simplicity just returns the default value in upper case. In a real world application, the callback would use the application's localisation.

In a real world application, the callback would look something like this:

const getLocaleText = (params) => {
    // to avoid key clash with external keys, we add 'studio' to the start of each key.
    const studioKey = 'studio.' + params.key;

    // look the value up using an application wide service
    return applicationLocaleService(studioKey);
}

Changing Locale Copy Link

Studio uses the locale as it is needed. It does not refresh as the locale changes. If your application allows changing the locale for the application, you must destroy and recreate Studio for it to use the new locale.

RTL Text Direction Copy Link

For languages that are displayed right to left, e.g. Hebrew and Arabic, the enableRtl property can be set to display in RTL format.