🌍 Quick, lightweight, and easy-to-use i18n engine for static websites https://vavilon.js.org/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Nikita Karamov 7fffd5790e
Update size-limit dependency
3 months ago
.github Reformat files 3 months ago
src Remove IE language fields 3 months ago
test/demo Update demo page 3 months ago
.eslintignore Update ESLint config 2 years ago
.eslintrc.json Rewrite ESLint config 3 months ago
.git-blame-ignore-revs Add .git-blame-ignore-revs 3 months ago
.gitignore Update gitignore 3 months ago
.prettierignore Add .prettierignore 3 months ago
CHANGELOG.md Reformat files 3 months ago
CONTRIBUTING.md Reformat files 3 months ago
LICENSE Initial commit 3 years ago
README.md Reformat files 3 months ago
package.json Update size-limit dependency 3 months ago
tsconfig.json Update TSConfig 3 months ago
vite.config.js Add Vite 3 months ago


vavilon.js logo


A quick, lightweight and easy-to-use i18n engine for static websites

npm npm bundle size

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:

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

  1. Create an HTML page or open an already existing one. Set the lang attribute in the <html> tag:

    <html lang="en">
        <title>Hello World!</title>
        <h1>How are you?</h1>

    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)

  2. 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 the vavilon class to these elements:

    <html lang="en">
        <title class="vavilon" data-vavilon="hello-world">Hello World!</title>
        <h1 class="vavilon" data-vavilon="how-are-you">How are you?</h1>
  3. 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": "Как дела?"
  4. Add each dictionary file to the page. Use a script element in the <head> with a data-vavilon-dict attribute holding the dictionary's language code:

  5. 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.

  6. 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:

Chrome Safari Firefox MS Edge Internet Explorer Opera
15+ 5+ 45+ 12+ 9+ 12.1+


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:

  <b class="vavilon" data-vavilon="hello-1">Hello</b>
  <span class="vavilon" data-vavilon="hello-2">world</span>!

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