Skip to content

A super lightweight JS library to provide translations on websites using language JSON files.

License

Notifications You must be signed in to change notification settings

thealphadollar/vanilla-i18n

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

44 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Welcome to vanilla-i18n ๐Ÿ‘‹

Version Documentation License: MIT Twitter: thealphadollar Github: thealphadollar All Contributors

vanilla-18n logo

A super lightweight JS script to provide internationalization to your website using translations from JSON files.

๐Ÿ  Demo Page

Motivation

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:

  1. create a CSV file of translations
  2. convert CSV to vanilla-i18n language JSONs
  3. import the script
  4. enclose text (to be translated) in i18n tags
  5. 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 js i18n!

Use Cases

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:

  1. only particular words / sentences
  2. a form present
  3. 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.

How To Use

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.

1. Create CSV File of Translations

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 select options 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 form should 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.

2. Convert CSV to vanilla-i18n Language JSONs

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.

3. Import The Script

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:

  1. languages: List of languages same as in the first row of language CSV or the names of the language JSON files without .json extension. The above snipper includes list of languages as per the example CSV.
  2. opts: These are optional arguments:
  3. path: Path to the language files relative to the root of the website. Default: assets/vanilla-i18n.
  4. debug: Shows debug information in browser console. Default: false.
  5. 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.
  6. toggler_id: ID of the select element for choosing language. Default: vanilla-i18n-toggler.
  7. default_language: Default language from the languages specified in the languages list. Default: languages[0]

4. Enclose Text In i18n tags

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.

5. Provide Language Selection

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 id of the select should be set as toggler_id provided in opts for vanilla_i18n in the Import The Script step above.
  • if you have an existing language toggler, set it's id as the provided toggler_id.
  • The value of options should be same as the CSV language heading or the language JSON filenames without .json extension.

Author

๐Ÿ‘ค Shivam Kumar Jha

๐Ÿค Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a โญ๏ธ if this project helped you!

๐Ÿ“ License

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.

Contributors โœจ

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