Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thealphadollar/vanilla-i18n
A super lightweight JS library to provide translations on websites using language JSON files.
https://github.com/thealphadollar/vanilla-i18n
choosing-language csv hacktoberfest i18n i18n-js internationalization json language-csv language-json-files language-jsons language-selection multilingual translation translations vanilla-js-plugin
Last synced: 10 days ago
JSON representation
A super lightweight JS library to provide translations on websites using language JSON files.
- Host: GitHub
- URL: https://github.com/thealphadollar/vanilla-i18n
- Owner: thealphadollar
- License: mit
- Created: 2020-09-18T17:38:43.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-08-26T10:42:44.000Z (about 1 year ago)
- Last Synced: 2024-10-11T20:16:32.036Z (26 days ago)
- Topics: choosing-language, csv, hacktoberfest, i18n, i18n-js, internationalization, json, language-csv, language-json-files, language-jsons, language-selection, multilingual, translation, translations, vanilla-js-plugin
- Language: JavaScript
- Homepage: https://thealphadollar.me/vanilla-i18n/
- Size: 314 KB
- Stars: 33
- Watchers: 4
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Welcome to vanilla-i18n 👋
> **A super lightweight JS script to provide internationalization to your website using translations from JSON files.**
### 🏠 [Demo Page](https://thealphadollar.me/vanilla-i18n/)
## 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:
0. only particular words / sentences
0. a form present
0. 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,
```csv
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](https://docs.google.com/spreadsheets/d/1KfPLetq4VUvEApiGtWEUuQUhAYCrocyLmyiHV2cl_ks/edit?usp=sharing) 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 `` tag.
```javascript
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();
```
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:
1. `path`: Path to the language files relative to the root of the website. Default: `assets/vanilla-i18n`.
2. `debug`: Shows debug information in browser console. Default: `false`.
3. `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`.
4. `toggler_id`: ID of the `select` element for choosing language. Default: `vanilla-i18n-toggler`.
5. `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.
```html
Name
comedy
romance
thriller
horror
biopic
```
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,
```html
English
हिन्दी
français
```
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**
* Website: [thealphadollar.me](https://thealphadollar.me)
* Twitter: [@thealphadollar\_](https://twitter.com/thealphadollar\_)
* Github: [@thealphadollar](https://github.com/thealphadollar)
* LinkedIn: [@thealphadollar](https://linkedin.com/in/thealphadollar)
## 🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/thealphadollar/vanilla-i18n/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). You can also take a look at the [contributing guide](https://github.com/thealphadollar/vanilla-i18n#contributing).
## Show your support
Give a ⭐️ if this project helped you!
## 📝 License
Copyright © 2020 [thealphadollar](https://github.com/thealphadollar).
This project is [MIT](https://github.com/thealphadollar/vanilla-i18n/blob/master/LICENSE) licensed.
The script is inspired from [Building a super small and simple i18n script in JavaScript](https://codeburst.io/translating-your-website-in-pure-javascript-98b9fa4ce427) by [
Andreas Remdt](https://github.com/andreasremdt).
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
rt
💻 📖 🤔 🔌 🔧
Denis Vieira
🚧
Shivam Kumar Jha
🚧
Randall Wert
🚧
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
***
_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_