A JS library for easily adding multiple languages to your site.
- Globalization is important for any website. Don't let language barriers bounce your customers away!
- Fast, seamless experience. The lightweight, ultra-fast translator helps your website win more likes!
- ZERO dependency!
- Easy to maintain. No more duplicating pages for different pages! The under-development system for auto-generating translation sheets will make it even easier for you to maintain your site!
- Self-controlled translation. Get rid of the uncertainty and inaccuracy from automatic translators! You define what's on your website for each language!
- Robust. Even if a step failed, your site content won't be affected!
- Deep Translating. You may even translate attributes of elements! In the future, you may even define actions when translating!
- Flexible language support, if you did not define a language for an element, a backup will be shown instead of leaving it blank!
- Secure! SHA256 signed encryption helps your customers to keep away from MIMA (Man In the Middle Attack).
- Easy to learn. Look at our example page to get a quick start!
- Easy to use, flexible API enables you to define your own translator behaviors, or directly bind a combobox!
- The detailed documentation and support helps you to smash any problems you meet! Example: https://85vocab.com
To apply multi-language.js to your website/apps, you may either:
Copy the code below and paste it inside your <head> element.
<script src="https://cdn.jsdelivr.net/gh/askask11/[email protected]/dist/multi-language.min.js" integrity="sha256-xL5PbSBwYLKYaUvdDP2S/lnF9s3oAPm/92GnACZBe2c=" crossorigin="anonymous"></script>
OR
- Download multi-language.js and serve it from your origin. Check out the releases of this repository to download the source code. Unzip it when finished.
Go to directory
distin the root folder, put filemulti-language.jsormulti-language.min.jsin your own web project folder and include it in your website. Example:
<script src="js/multi-language.min.js"></script>
Define a short code to represent each language.
For example, "zh" can stand for Chinese, and "en" stands for English.
Keep the documentation for your record.
Example:
| Code | Language |
| zh | Chinese |
| en | English |
| ... | ... |
Use them consistently once you defined them. They don't have to follow the standard guide but you may visit here for a reference.
Give id to all of the elements that will directly touch the text.
You may wrap your text with span element. For example,
<!--The id will be used to locate the element.-->
<div id="c1">Internationalization is very important, indeed.</div>
<!--You should label text-only children elements, and use their id for reference later.-->
<div>
<img src="img/image.png" >
<!--Label the element that is directly in contact with the text.-->
<span id="c2">
Do you really want to translate me?
</span>
<!--You may also include simple mark-ups for the text-->
<span id="c3">
Yes, because <strong>you<strong> are <u>not</u> fancy enough.
</span>
</div>
A translation sheet is a JSON Array containing the element IDs of the document and their respective inner texts in different languages.
This library will read the translation sheet and apply it to the document accordingly.
You may write the sheet in an external JSON file, or write it in a tag like <script id="translation-sheet" type="application/json">**YOUR TRANSLATION SHEET GOES HERE**</script> in the HTML page to be translated. Write it before the script activation.
Structure of the translation sheet:
A translation sheet is a JSON Array composed of multiple JSON Objects, and each them represents one element to be translated.
Simple Example of a translation sheet:
[
{
"id":"**THE ID OF THE TEXT ELEMENT**",
"langs":{
"en":"Hello!",
"es":"¡Hola!",
"zh":"你好(nihao)！"
}
},
{
"id":"**THE ID OF ANOTHER TEXT ELEMENT**",
"langs":{
"en":"Goodbye",
"es":"Adiós",
"zh":"再见"
}
},
{...},
{...},
......
]
Each of the JSON Object contains:
| Key | Datatype | Required | Explaination |
|---|---|---|---|
| id | String | Yes | The ID of the text element to be translated. When translating, all innerHTML or value of the targeted element will be updated. The ID should be unique across one document. |
| langs | JSON Object | No | The available translations for this element. It corresponds to 'innerHTML' property for normal elements, and 'value' attribute for <input /> and <textarea></textarea>. Note: Skip this part if you only wish to translate the attribute of an element, not its text on the UI. More details below |
| attr | JSON Object | No | Optionally, You may translate the attributes of an element. (ex. placeholder or title). This is an object containing what attribute should be translated and their respective translations. More details below |
Explaination for langs Object mentioned above,
for each langs JSON Object inside of the main object,
"lang":{
"**LANGUAGE**":"***TRANSLATION***",
"**LANGUAGE**":"***TRANSLATION***",
...
}
Explaination for attr object mentioned above,
"attr":
{
"**ATTRIBUTE NAME**":
{
"**LANGUAGE**":"***TRANSLATION***",
"**LANGUAGE**":"***TRANSLATION***",
....
},
"**ATTRIBUTE NAME**":
{
"**LANGUAGE**":"***TRANSLATION***",
"**LANGUAGE**":"***TRANSLATION***",
....
},
{...},
{...},
....
}
Complete example of a translation sheet:
Example HTML:
<img src="welcome.png">
<div id="welcome-txt">
Hello! (I am the default text)
</div>
<br>
...
<br>
<input placeholder="Enter Your Name" id="name-input">
<button id="farewell-btn" title="Thank you for visiting!" onclick="alert('Have a good day!');">
Goodbye!
</button>
Example JSON Translation sheet:
[
{
"id":"welcome-txt",
"langs":
{
"en":"Hello!",
"es":"¡Hola!",
"zh":"你好(nihao)！"
}
},
{
"id":"name-input",
"attr":
{
"placeholder":
{
"en":"Please enter your name",
"es":"Por favor ingrese su nombre aquí",
"zh":"请输入您的姓名"
}
}
},
{
"id":"farewell-btn",
"langs":
{
"en":"Goodbye",
"es":"Adiós",
"zh":"再见"
},"attr":
{
"title":
{
"en":"Thank you for visiting.",
"es":"Gracias por su visita.",
"zh":"谢谢访问！"
},"onclick":
{
"en":"alert('Have a good day!');",
"es":"alert('¡Que tenga un buen día!');",
"zh":"alert('祝您有美好的一天！');",
"ko":"alert('좋은 하루 되세요！');",
"vi":"alert('Chúc bạn ngày mới tốt lành');"
}
}
}
]
To activate translation feature on your website, you must construct a translator at the buttom of your HTML body.
The constructor of class MultiLanguage accepts 3 parameters, none of them is required.
var translator = new MultiLanguage(defaultLanguage(Optional), externalJSON(Optional), select(Optional));
| Sequence | Name | Datatype | Required | Default Value | Description |
|---|---|---|---|---|---|
| 1 | defaultLanguage | String |
No | en |
The default language for a user that has not defined any language preferences. This language must be available across ALL elements. You must assign a value here if the default language code is not "en". |
| 2 | externalJSON | JSONArray |
No | [] |
The translation sheet to load into the translator. The translator will load an empty array by default. You may load multiple sheets after it is constructed by calling method addSheet(translationSheet) |
| 3 | select | Element |
No | null |
An <select> element that has options containing supported languages. The current language will be changed to the value attribute of the <option> selected. You may register multiple selects later by calling method registerSelect(select) |
To load an external sheet file to the element, you can follow this example:
var xhr = new XMLHttpRequest(); //Create an xhr instance
var translator = new MultiLanguage(); // define translator, create a default instance
xhr.open("***HTTP METHOD TO USE***","***LINK TO YOUR SHEET.json***"); // Define target file and HTTP method to use.
xhr.onreadystatechange=(e)=>{
if(xhr.readyState === 4 && xhr.status === 200)
{
var jsonResponse = JSON.parse(xhr.responseText); // get response text and parse it into JSON.
translator.addSheet(jsonResponse);
}
}
xhr.send()
If you have written your translation sheet inside your HTML, you may follow this example
var json = JSON.parse(document.getElementById("translation-sheet").innerHTML);
var translator = new MultiLanguage("en",json);
You may repeat the steps above to load multiple sheets, but you may NOT load the same sheet more than once.
You can let user control the page language by defining a <select> element in your page. Then, register the <select> to the translator or pass the Element object of that select to the constructor. You may call function translate(language) manually too.
Example HTML Select
<select id="languages">
<option value="en">
English (Default)
</option>
<option value="zh">
简体中文
</option>
</select>
To Register(bind) this select to the translator instance:
var translator = new MultiLanguage(select=document.getElementById("languages")); // you may pass it to the constructor
or
var translator = new MultiLanguage();
translator.registerSelect(document.getElementById("languages")) // You may call method "registerSelect" to register it
Call the method above again, you may register multiple select elements. You may NOT register the same element more than once.
The register select element can control the global language settings, and will change accordingly when the language setting changes.
translate(json=this.externalJSON, target)
Translate all the elements on the translation sheet to target language. This will trigger all registered selects to select the "target" language.
| Parameter | Datatype | Required | Default Value | Description |
|---|---|---|---|---|
| json | JSONArray | No | this.externalJSON |
The translation sheet to run. By default, it will run the translaton sheet stored with the instance. Please call addSheet to add additional translation sheets. |
| target | String |
Yes | N/A | The target language code to translate to. If the language is not defined for a specifit element, the element or its attribute will be translated to the default language |
addSheet(jsonArray)
Add an additional sheet to the multilanguage translator. The sheet will be concatnated to the sheet added before. If there are duplicated entries, the one added later will override those added before. It will also invoke translate method to translate the elements indicated in the new sheet.
| Parameter | Datatype | Required | Default Value | Description |
|---|---|---|---|---|
| jsonArray | JSONArray | Yes | N/A | The JSONArray object of the sheet to be added. |
registerSelect(select)
Add a new select to the binding list. This select will also be able to control the global language and follow any changes.
| Parameter | Datatype | Required | Default Value | Description |
|---|---|---|---|---|
| select | Element |
Yes | N/A | The Element object of the select |
Find example.html in the root of the repo.
Jianqing Gao
Contact: [email protected]