{"id":16294719,"url":"https://github.com/thealphadollar/vanilla-i18n","last_synced_at":"2025-03-20T04:30:38.188Z","repository":{"id":49732735,"uuid":"296689963","full_name":"thealphadollar/vanilla-i18n","owner":"thealphadollar","description":"A super lightweight JS library to provide translations on websites using language JSON files.","archived":false,"fork":false,"pushed_at":"2023-08-26T10:42:44.000Z","size":322,"stargazers_count":33,"open_issues_count":3,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-28T23:02:04.794Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://thealphadollar.me/vanilla-i18n/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thealphadollar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-18T17:38:43.000Z","updated_at":"2024-09-25T08:40:24.000Z","dependencies_parsed_at":"2024-12-18T21:15:29.133Z","dependency_job_id":null,"html_url":"https://github.com/thealphadollar/vanilla-i18n","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fvanilla-i18n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fvanilla-i18n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fvanilla-i18n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fvanilla-i18n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thealphadollar","download_url":"https://codeload.github.com/thealphadollar/vanilla-i18n/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244047647,"owners_count":20389206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["choosing-language","csv","hacktoberfest","i18n","i18n-js","internationalization","json","language-csv","language-json-files","language-jsons","language-selection","multilingual","translation","translations","vanilla-js-plugin"],"created_at":"2024-10-10T20:16:16.437Z","updated_at":"2025-03-20T04:30:37.690Z","avatar_url":"https://github.com/thealphadollar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eWelcome to vanilla-i18n 👋\u003c/h1\u003e\n\u003cp\u003e\n  \u003ca href=\"https://www.npmjs.com/package/vanilla-i18n\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Version\" src=\"https://img.shields.io/npm/v/vanilla-i18n.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/thealphadollar/vanilla-i18n/blob/master/README.md\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/thealphadollar/vanilla-i18n/blob/master/LICENSE\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/thealphadollar\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Twitter: thealphadollar\" src=\"https://img.shields.io/twitter/follow/thealphadollar.svg?style=social\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/thealphadollar?tab=followers\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Github: thealphadollar\" src=\"https://img.shields.io/github/followers/thealphadollar.svg?style=social\u0026label=Follow\u0026maxAge=2592000\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#contributors-\"\u003e\n    \u003cimg alt=\"All Contributors\" src=\"https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cimg align=\"center\" alt=\"vanilla-18n logo\" src=\"docs/assets/logo.png\" /\u003e\n\n\u003e **A super lightweight JS script to provide internationalization to your website using translations from JSON files.**\n\n### 🏠 [Demo Page](https://thealphadollar.me/vanilla-i18n/)\n\n## Motivation\n\nThis 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: \n\n1. create a CSV file of translations\n2. convert CSV to `vanilla-i18n` language JSONs\n3. import the script\n4. enclose text (to be translated) in `i18n` tags\n5. provide language selection\n\nVoila! Your visitors can now see the content you have translated without any large overhead, delay, or using sophisticated libraries on your side.\n\n\u003e It's plain vanilla ~js~ i18n!\n\n## Use Cases\n\nThe 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:\n\n0. only particular words / sentences\n0. a form present\n0. only certain sections\n\nThe 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.\n\n## How To Use\n\nThe script is simple to add to your website, and following are the details of each of the required steps.\n\nNOTE: 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.\n\n### 1. Create CSV File of Translations\n\n`vanilla-i18n` requires you to have a key and corresponding language mappings of the key. An example CSV is below,\n\n```csv\nvanilla-i18n-key,English,हिन्दी,français\nlanguage,Language,भाषा,भाषा,Langue\nform.name,Name,नाम,Nom\n```\n\nSalient features are:\n\n- first row must provide languages following the key entry (and should be same as the `select` options for choosing language)\n- first column must be the key for replacement (used later to perform replacement in the HTML)\n- nested keys are supported, and nesting is depicted by \".\" (for example, \"form.desc\")\n- same key cannot exist in unnested form, for eg. in above CSV, a key `form` should not exist\n- 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.\n\n### 2. Convert CSV to `vanilla-i18n` Language JSONs\n\nWith 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`.\n\nProvide these language JSON files in your hosting server, default is inside directory `assets/vanilla-i18n` in the root folder of your website.\n\n### 3. Import The Script\n\nImport the JS in all the HTML pages where the translation is required by including the below snippet right after `\u003chead\u003e` tag.\n\n\n```javascript\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/thealphadollar/vanilla-i18n/src/vanilla-i18n.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const languages = [\n    \"English\",\n    \"हिन्दी\",\n    \"français\"\n  ];\n  new vanilla_i18n (\n    languages,\n    opts = {\n      path: \"assets/vanilla-i18n\",\n      debug: false,\n      i18n_attr_name: \"vanilla-i18n\",\n      toggler_id: \"vanilla-i18n-toggler\",\n      default_language: languages[0],\n    }\n  ).run();\n\u003c/script\u003e\n```\n\nThe `vanilla-i18n` objects takes the following arguments:\n\n1. `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.\n2. `opts`: These are optional arguments:\n  1. `path`: Path to the language files relative to the root of the website. Default: `assets/vanilla-i18n`.\n  2. `debug`: Shows debug information in browser console. Default: `false`.\n  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`.\n  4. `toggler_id`: ID of the `select` element for choosing language. Default: `vanilla-i18n-toggler`.\n  5. `default_language`: Default language from the languages specified in the `languages` list. Default: `languages[0]`\n\n### 4. Enclose Text In `i18n` tags\n\nAny text, word, paragraph, sentence, etc. that needs to be translated is to be enclosed as follows.\n\n```html\n\u003ci18n vanilla-i18n=\"form.name\"\u003eName\u003c/i18n\u003e\n\u003ci18n vanilla-i18n=\"form.movies.options\"\u003e\u003cselect name=\"moviepref\"\u003e\n    \u003coption value=1 selected=\"true\"\u003e\n        comedy\n    \u003c/option\u003e\n    \u003coption value=2\u003e\n        romance\n    \u003c/option\u003e\n    \u003coption value=3\u003e\n        thriller\n    \u003c/option\u003e\n    \u003coption value=4\u003e\n        horror\n    \u003c/option\u003e\n    \u003coption value=5\u003e\n        biopic\n    \u003c/option\u003e\n\u003c/select\u003e\n\u003c/i18n\u003e\n```\n\nThe attribute `vanilla-i18n` points to the key to be matched in the language JSON for replacement.\n\nAs seen in the above example, entire HTML elements or any section of the HTML can be replaced.\n\n### 5. Provide Language Selection\n\nProvide users language selection via `select` input tag. An example of the same, corresponding to above CSV, is,\n\n```html\n\u003cselect id=\"vanilla-i18n-toggler\"\u003e\n  \u003coption\u003eEnglish\u003c/option\u003e\n  \u003coption\u003eहिन्दी\u003c/option\u003e\n  \u003coption\u003efrançais\u003c/option\u003e\n\u003c/select\u003e\n```\n\nFollowing key points should be checked for proper functioning of the script:\n\n- The `id` of the select should be set as `toggler_id` provided in `opts` for `vanilla_i18n` in the `Import The Script` step above.\n- if you have an existing language toggler, set it's `id` as the provided `toggler_id`.\n- The value of options should be same as the CSV language heading or the language JSON filenames without `.json` extension.\n\n## Author\n\n👤 **Shivam Kumar Jha**\n\n* Website: [thealphadollar.me](https://thealphadollar.me)\n* Twitter: [@thealphadollar\\_](https://twitter.com/thealphadollar\\_)\n* Github: [@thealphadollar](https://github.com/thealphadollar)\n* LinkedIn: [@thealphadollar](https://linkedin.com/in/thealphadollar)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel 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).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## 📝 License\n\nCopyright © 2020 [thealphadollar](https://github.com/thealphadollar).\u003cbr /\u003e\nThis project is [MIT](https://github.com/thealphadollar/vanilla-i18n/blob/master/LICENSE) licensed.\n\nThe 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 [\nAndreas Remdt](https://github.com/andreasremdt).\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/toyamarodrigo\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/41844101?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ert\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thealphadollar/vanilla-i18n/commits?author=toyamarodrigo\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/thealphadollar/vanilla-i18n/commits?author=toyamarodrigo\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#ideas-toyamarodrigo\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#plugin-toyamarodrigo\" title=\"Plugin/utility libraries\"\u003e🔌\u003c/a\u003e \u003ca href=\"#tool-toyamarodrigo\" title=\"Tools\"\u003e🔧\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://denisvieira.js.org/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/8844649?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDenis Vieira\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#maintenance-denisvieira05\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/thealphadollar\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/32812320?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eShivam Kumar Jha\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#maintenance-thealphadollar\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/RandallWert\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/20331611?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRandall Wert\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#maintenance-RandallWert\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n***\n_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthealphadollar%2Fvanilla-i18n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthealphadollar%2Fvanilla-i18n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthealphadollar%2Fvanilla-i18n/lists"}