A super lightweight JS script to provide internationalization to your website using translations from JSON files.
๐ Demo Page
This library aims to solve the problem of providing internationalization (translations) to a part or entirety of your website, to certain paragraphs, to words, or to any another granular level desired. There are five simple steps to achieving this:
- create a CSV file of translations
- convert CSV to
vanilla-i18nlanguage JSONs - import the script
- enclose text (to be translated) in
i18ntags - provide language selection
Voila! Your visitors can now see the content you have translated without any large overhead, delay, or using sophisticated libraries on your side.
It's plain vanilla
jsi18n!
The purpose of the script is to make it as simple as possible to implement translations in a website. Following are some translation cases for the script:
- only particular words / sentences
- a form present
- only certain sections
The script is not efficient if you wish to translate entire pages and best suited when only a segment of the webpage is required to be translated.
The script is simple to add to your website, and following are the details of each of the required steps.
NOTE: The script does NOT provide translations by itself; the developer is expected to manually (or otherwise) write translations for each of the text for each desired language.
vanilla-i18n requires you to have a key and corresponding language mappings of the key. An example CSV is below,
vanilla-i18n-key,English,เคนเคฟเคจเฅเคฆเฅ,franรงais
language,Language,เคญเคพเคทเคพ,เคญเคพเคทเคพ,Langue
form.name,Name,เคจเคพเคฎ,Nom
Salient features are:
- first row must provide languages following the key entry (and should be same as the
selectoptions for choosing language) - first column must be the key for replacement (used later to perform replacement in the HTML)
- nested keys are supported, and nesting is depicted by "." (for example, "form.desc")
- same key cannot exist in unnested form, for eg. in above CSV, a key
formshould not exist - an easy way to create language translations is using a Google Sheet and
=GOOGLETRANSLATE(COLUMN,SRC_LNG,DEST_LNG). Refer this sheet for example. Thereafter, just export the sheet in CSV format.
With the provided script (more details in csv_to_vanilla-i18n), convert the CSV to languages JSONs. The filename is based on the first row of the CSV. For eg. for the above CSV, the generated JSON are English.json, เคนเคฟเคจเฅเคฆเฅ.json, and franรงais.json.
Provide these language JSON files in your hosting server, default is inside directory assets/vanilla-i18n in the root folder of your website.
Import the JS in all the HTML pages where the translation is required by including the below snippet right after <head> tag.
<script src="https://cdn.jsdelivr.net/gh/thealphadollar/vanilla-i18n/src/vanilla-i18n.min.js"></script>
<script>
const languages = [
"English",
"เคนเคฟเคจเฅเคฆเฅ",
"franรงais"
];
new vanilla_i18n (
languages,
opts = {
path: "assets/vanilla-i18n",
debug: false,
i18n_attr_name: "vanilla-i18n",
toggler_id: "vanilla-i18n-toggler",
default_language: languages[0],
}
).run();
</script>The vanilla-i18n objects takes the following arguments:
languages: List of languages same as in the first row of language CSV or the names of the language JSON files without.jsonextension. The above snipper includes list of languages as per the example CSV.opts: These are optional arguments:path: Path to the language files relative to the root of the website. Default:assets/vanilla-i18n.debug: Shows debug information in browser console. Default:false.i18n_attr_name: Name of the data attribute storing the key to be used for translation of the enclosed text (more in next section). Default:vanilla-i18n.toggler_id: ID of theselectelement for choosing language. Default:vanilla-i18n-toggler.default_language: Default language from the languages specified in thelanguageslist. Default:languages[0]
Any text, word, paragraph, sentence, etc. that needs to be translated is to be enclosed as follows.
<i18n vanilla-i18n="form.name">Name</i18n>
<i18n vanilla-i18n="form.movies.options"><select name="moviepref">
<option value=1 selected="true">
comedy
</option>
<option value=2>
romance
</option>
<option value=3>
thriller
</option>
<option value=4>
horror
</option>
<option value=5>
biopic
</option>
</select>
</i18n>The attribute vanilla-i18n points to the key to be matched in the language JSON for replacement.
As seen in the above example, entire HTML elements or any section of the HTML can be replaced.
Provide users language selection via select input tag. An example of the same, corresponding to above CSV, is,
<select id="vanilla-i18n-toggler">
<option>English</option>
<option>เคนเคฟเคจเฅเคฆเฅ</option>
<option>franรงais</option>
</select>Following key points should be checked for proper functioning of the script:
- The
idof the select should be set astoggler_idprovided inoptsforvanilla_i18nin theImport The Scriptstep above. - if you have an existing language toggler, set it's
idas the providedtoggler_id. - The value of options should be same as the CSV language heading or the language JSON filenames without
.jsonextension.
๐ค Shivam Kumar Jha
- Website: thealphadollar.me
- Twitter: @thealphadollar_
- Github: @thealphadollar
- LinkedIn: @thealphadollar
Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.
Give a โญ๏ธ if this project helped you!
Copyright ยฉ 2020 thealphadollar.
This project is MIT licensed.
The script is inspired from Building a super small and simple i18n script in JavaScript by Andreas Remdt.
Thanks goes to these wonderful people (emoji key):
 rt ๐ป ๐ ๐ค ๐ ๐ง |
 Denis Vieira ๐ง |
 Shivam Kumar Jha ๐ง |
 Randall Wert ๐ง |
This project follows the all-contributors specification. Contributions of any kind welcome!
This README was generated with โค๏ธ by readme-md-generator