Translation management
This module is used to manage the translations of static and dynamic texts.
What's the difference between static and dynamic texts?
- Static: The texts which are used in the general interface (buttons, menus, etc.) and loaded from a static file
- Dynamic: The texts which are defined by the user (application names, view names, model names, field labels, etc.) and loaded from the database.
Use case:
- You build a SaaS application and you want to provide a multi-language interface, through static texts.
- User can build their own application, with their own views, models, fields, etc. and you want to provide them a multi-language interface for those dynamic texts.
Members
# static texts
All the static texts used by KissJS library
- English is the reference language
- keys prefixed with a # indicate they are a text code, therefore, they need a translation in every language
- keys with no English translation means the key is the English text (no need to translate it)
- in case a text is not translated in a specific language, the English text will be used as fallback, but it's not normal.
Current supported languages:
- English (en)
- French (fr)
- Spanish (es)
Methods
# static get() → {object}
Get the current static and dynamic languages
- The current static and dynamic languages. Example: {static: "en", dynamic: "it"}
object
# static getLanguageName(code) → {string}
Get the language name from the code
Parameters:
| Name | Type | Description |
|---|---|---|
code |
string
|
- The language name
string
Example
kiss.language.getLanguageName("en") // English
kiss.language.getLanguageName("fr") // Français# static init(loadAllLanguagesopt)
Init the current languages for the interface (static texts) and for the user-defined texts (dynamic texts).
- first check the url parameter "language" (for example: &language=fr)
- if no parameter, tries to get the browser language
- defaults to "en" (English)
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
loadAllLanguages |
boolean
|
<optional> |
If true, load all the languages available in the library. Default is false. |
# async static loadLibraryTexts(loadAllLanguagesopt) → {Promise}
Load the library texts
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
loadAllLanguages |
boolean
|
<optional> |
If true, load all the languages available in the library. Default is false. |
- A promise that resolves when the texts are loaded
Promise
# static select(config)
Open a window to switch the languages:
- static language, for the interface
- dynamic language (if the parameter "dynamic" is set to true)
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
config |
object
|
Configuration object |
|
static |
boolean
|
<optional> |
Allow to select the interface languages, among the available languages. Default is true. |
dynamic |
boolean
|
<optional> |
If true, show a dropdown list to select the content language. Default is false. |
# static set(newLanguage)
Switch language for the interface (static texts)
Parameters:
| Name | Type | Description |
|---|---|---|
newLanguage |
string
|
# static setAvailable(languages)
Set the available interface languages
Parameters:
| Name | Type | Description |
|---|---|---|
languages |
Array.<object>
|
Passed as an array of objects with a "code" and a "name" property |
this
Example
kiss.language.setAvailable([
{
code: "en",
name: "English"
},
{
code: "fr",
name: "Français"
},
{
code: "es",
name: "Español"
}
])# static setDynamic(newLanguage)
Switch language for user-defined texts (dynamic texts)
Parameters:
| Name | Type | Description |
|---|---|---|
newLanguage |
string
|
# static showMissingTexts() → {string}
Show all missing texts in the console
- All the missing texts
string
# static showTranslationWindow()
Show a window to translate texts without translation
# static translate(key, customSourceTextsopt, merge) → {string}
Return a localized text from a key, or a fallback text If a translation is missing, the text key is stored into the "kiss.language.missingTexts" array, in order to help fixing the missing translations. When a merge object is passed as a parameter, the values are merged into the final string.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
key |
string
|
The text key, which should be in lowercase by convention (txtTitleCase, txtUpperCase, and txtLowerCase handle the case) |
|
customSourceTexts |
object
|
<optional> |
Custom source texts. Must be provided in the same format as default source texts. See example. |
merge |
object
|
Contextual data that must be merged into the text |
- The localized text, or the key passed to the function if not found
string
Example
txt("hello") // bonjour
txtTitleCase("hello") // Bonjour
txt("hello %firstName %lastName", null, {firstName: "Bob", lastName: "Wilson"}) // bonjour Bob Wilson
txt("Devil number: %num%num%num", null, {num: 6}) // Devil number: 666
let customSource = {
"apple": {
fr: "pomme"
},
"banana": {
fr: "banana"
},
"fruits": {
en: "choose between those fruits...",
fr: "choisissez parmi ces fruits..."
}
}
kiss.language.set("en")
txtTitleCase("apple", customSource) // Apple
txtUpperCase("banana", customSource) // BANANA
txtTitleCase("fruits", customSource) // Choose between those fruits...
kiss.language.set("fr")
txtUpperCase("fruits", customSource) // CHOISISSEZ PARMI CES FRUITS...# static translateProperty(obj, key) → {*}
Return a localized text from a key, or a fallback text. By convention, if a property has a translation, it should be named "propertyTranslations" (for example: nameTranslations).
Parameters:
| Name | Type | Description |
|---|---|---|
obj |
object
|
|
key |
string
|
- The localized text, or the original property if not found
*