Language – amCharts 4 Documentation

Type class

Handles all language-related tasks, like loading and storing translations, translating prompts, lists of prompts and even functions.

Almost every object in amCharts4 universe will have a language property, which can be accessed for prompt translation.

ILanguageAdapters for a list of available Adapters
@todo Make prompt keys case-insensitive

Sources

Language can be used (imported) via one of the following packages.

/**
 * --------------------------------------------------------
 * Import from: "core.ts"
 * Use like: am4core.Language
 * --------------------------------------------------------
 */
import * as am4core from "@amcharts/amcharts4/core";

/**
 * --------------------------------------------------------
 * Include via: <script src="core.js"></script>
 * Access items like: am4.Language
 * --------------------------------------------------------
 */

Inheritance

Language extends BaseObjectEvents.

Language is not extended by any other symbol.

Properties

adapter #	Type `Adapter` < `this`, `ILanguageAdapters` > Default `new Adapter(this)` Adapter.
clonedFrom #	Type `$type.Optional` < `this` > Inherited from `BaseObject` Reference to the original object this object was cloned from. We need to keep this so we can disassociate it from source object when this object is disposed.
config #	Type `object` Inherited from `BaseObject` Use this property to set JSON-based config. When set, triggers processing routine, which will go through all properties, and try to apply values, create instances, etc. Use this with caution, as it is a time-consuming process. It's used for initialchart setup only, not routine operations.
events #	Type `EventDispatcher` < `AMEvent` < `this`, `ILanguageEvents` > > Inherited from `BaseObjectEvents` An `EventDispatcher` instance
id #	Type `$type.Optional` < `string` > Inherited from `BaseObject` Sets the user-defined id of the element.
locale #	Type `ILocale` Current locale.
uid #	Type `string` Inherited from `BaseObject` Returns object's internal unique ID.
There are 5 inherited items currently hidden from this list.

Methods

clone( cloneId?: `string` ) #	Returns `this` Inherited from `BaseObject` Makes a copy of this object and returns the clone. Try to avoid cloning complex objects like chart, create new instances if you need them.
constructor() #	Returns `Language` Constructor
copyFrom( source: `this` ) #	Returns `void` Inherited from `BaseObjectEvents` Copies all parameters from another `Sprite`.
dispatch( eventType: `Key`, data?: `any` ) #	Returns `void` Inherited from `BaseObjectEvents` Dispatches an event using own event dispatcher. Will automatically populate event data object with event type and target (this element). It also checks if there are any handlers registered for this sepecific event.
dispatchImmediately( eventType: `Key`, data?: `any` ) #	Returns `void` Inherited from `BaseObjectEvents` Works like `dispatch`, except event is triggered immediately, without waiting for the next frame cycle.
dispose() #	Returns `void` Inherited from `BaseObject` Destroys this object and all related data.
getCurrentThemes() #	Returns `ITheme[]` Inherited from `BaseObject` Returns a list of themes that should be applied to this element. It could either be a list of themes set explicitly on this element, or system-wide.
isDefault() #	Returns `boolean` Returns `true` if the currently selected locale is a default locale.
isDisposed() #	Returns `boolean` Inherited from `BaseObject` Returns if this object has been already been disposed.
setTranslationAny( prompt: `string`, translation: `string`, locale?: `ILocale` ) #	Returns `void` Sets a prompt translation. @since 4.9.35
translate( prompt: `Key`, locale?: `ILocale`, rest: `Array` < `string` > ) #	Returns `string` Returns the translation of the string. If the translation is empty, it will return untranslated prompt. Third parameter and up are strings that can be used to replace "%X" placeholders in prompt. E.g.: // Results in "This is a first translation test" chart.language.translate("This is a %1 translation %2", null, "first", "test"); // Results in "This is a first translation test" chart.language.translate("This is a %1 translation %2", null, "first", "test");
translateAll( list: `Array` < `Key` > , locale?: `ILocale` ) #	Returns `Array` < `string` > Translates a list of prompts in one go.
translateAny( prompt: `string`, locale?: `ILocale`, rest: `Array` < `string` > ) #	Returns `string` Non-type-checked translation. Can be used by plugins and other code that may have their own non-standard translation prompts. @since 4.5.5
translateEmpty( prompt: `Key`, locale?: `ILocale`, rest: `Array` < `string` > ) #	Returns `string` Translates prompt. If translation is empty, it will return empty string, which is a different behavior than that of regular `translate`.
translateFunc( prompt: `Key`, locale?: `ILocale` ) #	Returns `ILocaleFunctions[""]` Translates a function. This method will return a function reference, but will not run it. It's up to the caller script to run the function. @todo Apply adapter
There are 7 inherited items currently hidden from this list.

clone(

cloneId?: string

)

Returns this

Inherited from BaseObject

Makes a copy of this object and returns the clone. Try to avoid cloning complex objects like chart, create new instances if you need them.

constructor()

Returns Language

Constructor

copyFrom(

source: this

)

Returns void

Inherited from BaseObjectEvents

Copies all parameters from another Sprite.

dispatch(

eventType: Key,
data?: any

)

Returns void

Inherited from BaseObjectEvents

Dispatches an event using own event dispatcher. Will automatically populate event data object with event type and target (this element).

It also checks if there are any handlers registered for this sepecific event.

dispatchImmediately(

eventType: Key,
data?: any

)

Returns void

Inherited from BaseObjectEvents

Works like dispatch, except event is triggered immediately, without waiting for the next frame cycle.

dispose()

Returns void

Inherited from BaseObject

Destroys this object and all related data.

getCurrentThemes()

Returns ITheme[]

Inherited from BaseObject

Returns a list of themes that should be applied to this element. It could either be a list of themes set explicitly on this element, or system-wide.

isDefault()

Returns boolean

Returns true if the currently selected locale is a default locale.

isDisposed()

Returns boolean

Inherited from BaseObject

Returns if this object has been already been disposed.

setTranslationAny(

prompt: string,
translation: string,
locale?: ILocale

)

Returns void

Sets a prompt translation.

@since 4.9.35

translate(

prompt: Key,
locale?: ILocale,
rest: Array < string >

)

Returns string

Returns the translation of the string.

If the translation is empty, it will return untranslated prompt.

Third parameter and up are strings that can be used to replace "%X" placeholders in prompt.

E.g.:

// Results in "This is a first translation test"
chart.language.translate("This is a %1 translation %2", null, "first", "test");

// Results in "This is a first translation test"
chart.language.translate("This is a %1 translation %2", null, "first", "test");

translateAll(

list: Array < Key > ,
locale?: ILocale

)

Returns Array < string >

Translates a list of prompts in one go.

translateAny(

prompt: string,
locale?: ILocale,
rest: Array < string >

)

Returns string

Non-type-checked translation.

Can be used by plugins and other code that may have their own non-standard translation prompts.

@since 4.5.5

translateEmpty(

prompt: Key,
locale?: ILocale,
rest: Array < string >

)

Returns string

Translates prompt.

If translation is empty, it will return empty string, which is a different behavior than that of regular translate.

translateFunc(

prompt: Key,
locale?: ILocale

)

Returns ILocaleFunctions[""]

Translates a function.

This method will return a function reference, but will not run it. It's up to the caller script to run the function.

@todo Apply adapter

There are 7 inherited items currently hidden from this list.

Events

#localechanged	Param { locale: `ILocale`, type: `"localechanged"`, target: `this` } Invoked when locale is changed by user.

#localechanged

Param { locale: ILocale,
type: "localechanged",
target: this }

Invoked when locale is changed by user.

Adapters

#locale	Param { locale: `ILocale` } Applied to result whenever retrieving currently set locale.
#translate	Param { locale: `ILocale`, translation: `string` } Applied to a translation.
#translations	Param { locale: `ILocale`, translations: `any` } Applied to all of the locale translations.

#locale

Param { locale: ILocale }

Applied to result whenever retrieving currently set locale.

#translate

Param { locale: ILocale,
translation: string }

Applied to a translation.

#translations

Param { locale: ILocale,
translations: any }

Applied to all of the locale translations.