Saved searches
Use saved searches to filter your results more quickly
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
A JS library for easily adding multiple languages to your site.
License
askask11/multi-language
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Sign In Required
Please sign in to use Codespaces.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching Xcode
If nothing happens, download Xcode and try again.
Launching Visual Studio Code
Your codespace will open once ready.
There was a problem preparing your codespace, please try again.
Latest commit
Git stats
Files
Failed to load latest commit information.
README.md
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:
Use a CDN service (recommended)
Copy the code below and paste it inside your element.
- 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 dist in the root folder, put file multi-language.js or multi-language.min.js in your own web project folder and include it in your website. Example:
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,
Internationalization is very important, indeed. 
Do you really want to translate me? Yes, because you are not fancy enough. 
3. Create JSON Translation Sheet(s)
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 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:
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 and . 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,
Explaination for attr object mentioned above,
Complete example of a translation sheet:
Example HTML:
Hello! (I am the default text)
.
Example JSON Translation sheet:
4. Construct a MultiLanguage instance
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 element that has options containing supported languages. The current language will be changed to the value attribute of the selected. You may register multiple selects later by calling method registerSelect(select) |
5. Load translation sheet into the instance
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.
6. Register Select Elements
You can let user control the page language by defining a element in your page. Then, register the 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
To Register(bind) this select to the translator instance:
var translator = new MultiLanguage(select=document.getElementById("languages")); // you may pass it to the constructor 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.
Congratulations! Your website can speak multiple languages now!
Functions Reference Sheet
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 |
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. |
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.