Skip to content

Latest commit

 

History

History
216 lines (160 loc) · 10.2 KB

README.md

File metadata and controls

216 lines (160 loc) · 10.2 KB
Raw

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