THIS PROJECT IS UNMAINTAINED
I do not develop this project any more. The closest alternative would be i18next.
How to Install
To use vavilon.js
on your website you need to add it as a script to your
page's <head>
. Here are some ways to get this done:
via CDN (recommended)
You can get vavilon.js
via jsDelivr. This is the fastest and the most reliable
way:
<script src="https://cdn.jsdelivr.net/npm/vavilon@1/dist/vavilon.min.js"></script>
via NPM
If build your static website with help of other NPM packages, you can install
vavilon.js
using npm:
npm install vavilon
Then you can include the script in your webpage like so:
<script src="./path/to/node_modules/vavilon/dist/vavilon.min.js"></script>
Manual download
You can find the latest version of vavilon.js
in the Releases
section on GitHub. Download the minified version and include it in your page:
<script src="./path/to/vavilon.min.js"></script>
How to use
-
Create an HTML page or open an already existing one. Set the
lang
attribute in the<html>
tag:<html lang="en"> <head> <title>Hello World!</title> </head> <body> <h1>How are you?</h1> </body> </html>
If you rely on multiple versions of the same language (like US vs UK English), you can user the country-specific language codes (i.e.
en-US
,en-UK
) -
Assign a unique ID to every element on the HTML page the contents of which you want to have translated. Put the IDs in the
data-vavilon
attribute and add thevavilon
class to these elements:<html lang="en"> <head> <title class="vavilon" data-vavilon="hello-world">Hello World!</title> </head> <body> <h1 class="vavilon" data-vavilon="how-are-you">How are you?</h1> </body> </html>
-
Create JSON dictionary files for every language you want to support. Each file should be an object, with keys being the unique IDs and values being the translated strings. Here's how it would look for Russian:
{ "hello-world": "Привет мир!", "how-are-you": "Как дела?" }
-
Add each dictionary file to the page. Use a
script
element in the<head>
with adata-vavilon-dict
attribute holding the dictionary's language code:<script type="application/json" src="path/to/ru.json" data-vavilon-dict="ru" ></script>
-
Add the latest version of
vavilon.js
to the page. Now your page will automatically change its language based on the end user's browser locale. -
If you want your user to be able to switch languages manually, you can set it up by using the exported
setLang
function:<button onclick="setLang('en')">English version</button>
Browser support
vavilon.js
works on 99% of browsers used today:
15+ | 5+ | 45+ | 12+ | 9+ | 12.1+ |
Caveats
Despite being a stable release, vavilon.js
is not completely finished. Here
are some things that are not yet supported or don't work as expected:
Styling and inline tags
Right now vavilon.js
replaces the text of the elements, not their HTML code.
Consider this snippet:
<p class="vavilon" data-vavilon="hello"><b>Hello</b> world!</p>
The page will not have the word "Hello" in bold upon changing the language,
because vavilon.js
will have replaced the contents of the whole <p>
with
plain text.
The support for styling your strings will come in future releases. If this is crucial for you right now, you can use a workaround like this:
<p>
<b class="vavilon" data-vavilon="hello-1">Hello</b>
<span class="vavilon" data-vavilon="hello-2">world</span>!
</p>
This way you can define separate IDs for the words "Hello" and "world" in your dictionary file and have different styles applied to them on the page.
Framework compatibility
While it is possible to create static websites using frameworks like Vue.js, React and Svelte, the support not been tested at all. If you use these frameworks to generate your website, I highly recommend you use something else, like the i18n engines created specifically for these frameworks.
Regarding jQuery, it has not been tested yet either, but I guess it should work
just fine. If you want to play around with vavilon.js
and jQuery, I encourage
you do so.
If you encounter any bugs, don't hesitate creating an issue