{"id":15282781,"url":"https://github.com/wikimedia/banana-i18n","last_synced_at":"2025-04-12T18:51:03.858Z","repository":{"id":33697727,"uuid":"157863227","full_name":"wikimedia/banana-i18n","owner":"wikimedia","description":"banana-i18n - Javascript Internationalization library","archived":false,"fork":false,"pushed_at":"2024-10-29T09:40:51.000Z","size":932,"stargazers_count":78,"open_issues_count":10,"forks_count":27,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-29T11:44:57.319Z","etag":null,"topics":["i18n","javascript","javascript-library","l10n"],"latest_commit_sha":null,"homepage":"https://wikimedia.github.io/banana-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/wikimedia.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":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-16T12:15:46.000Z","updated_at":"2024-10-28T19:43:31.000Z","dependencies_parsed_at":"2024-06-18T15:35:21.981Z","dependency_job_id":"4a43d792-ac1a-4a83-b46f-4b86baa512cd","html_url":"https://github.com/wikimedia/banana-i18n","commit_stats":{"total_commits":95,"total_committers":12,"mean_commits":7.916666666666667,"dds":0.2315789473684211,"last_synced_commit":"aab43de1e0ba4b729d916a4423d5162445c6d1ba"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Fbanana-i18n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Fbanana-i18n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Fbanana-i18n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikimedia%2Fbanana-i18n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wikimedia","download_url":"https://codeload.github.com/wikimedia/banana-i18n/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618223,"owners_count":21134199,"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":["i18n","javascript","javascript-library","l10n"],"created_at":"2024-09-30T14:39:53.366Z","updated_at":"2025-04-12T18:51:03.825Z","avatar_url":"https://github.com/wikimedia.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# banana-i18n - Javascript Internationalization library\n\n[![Build](https://github.com/wikimedia/banana-i18n/actions/workflows/node.js.yml/badge.svg)](https://github.com/wikimedia/banana-i18n/actions/workflows/node.js.yml)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wikimedia/banana-18n/blob/master/LICENSE)\n[![npm version](https://img.shields.io/npm/v/banana-i18n.svg?style=flat)](https://www.npmjs.com/package/banana-i18n)\n\nbanana-i18n is a javascript internationalization library that uses \"banana\" format - A JSON based localization file format.\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Node.js](#nodejs)\n  - [JavaScript](#javascript)\n- [Demo](#demo)\n- [Developer Documentation](#developer-documentation)\n  - [Banana File format](#banana-file-format)\n  - [Loading the messages](#loading-the-messages)\n    - [Using the constructor](#using-the-constructor)\n    - [Load the messages for a locale](#load-the-messages-for-a-locale)\n    - [Load the messages for many locales at once](#load-the-messages-for-many-locales-at-once)\n  - [Setting the locale](#setting-the-locale)\n  - [Fallback](#fallback)\n  - [Placeholders](#placeholders)\n  - [Plurals](#plurals)\n  - [Gender](#gender)\n  - [Grammar](#grammar)\n  - [Directionality-safe isolation](#directionality-safe-isolation)\n  - [Wiki style links](#wiki-style-links)\n  - [Extending the parser](#extending-the-parser)\n  - [Message documentation](#message-documentation)\n  - [Translation](#translation)\n  - [Frameworks](#frameworks)\n- [Thanks](#thanks)\n\n## Features\n\n- Simple file format - JSON. Easily readable for humans and machines.\n- Bindings and wrappers available for React.js and Vue.js. See [frameworks](#frameworks) sections.\n- Author and metadata information is not lost anywhere. There are other file formats using comments to store this.\n- Uses MediaWiki convention for placeholders. Easily readable and proven convention. Example: ```There are $1 cars```\n- Supports plural conversion without using extra messages for all plural forms. Plural rule handling is done using CLDR. Covers a wide range of languages\n- Supports gender. By passing the gender value, you get correct sentences according to gender.\n- Supports grammar forms. banana-i18n has a basic but extensible grammar conversion support\n- Fallback chains for all languages.\n- Nestable grammar, plural, gender support. These constructs can be nested to any arbitrary level for supporting sophisticated message localization\n- Message documentation through special language code ```qqq```\n- Extensible message parser to add or customize magic words in the messages. Example: ```{sitename}``` or ```[[link]]```\n- Automatic message file linter using [banana-checker](https://www.npmjs.com/package/grunt-banana-checker)\n- Tested in production - MediaWiki and and its extensions use this file format\n\n## Installation\n\n```\nnpm i banana-i18n\n```\n## Usage\n\n### Node.js\n\n```js\nconst Banana = require('banana-i18n');\n\n// Initialize Banana-i18n with the default locale and messages\nconst banana = new Banana('en', {\n    messages: {\n        'greet-user': 'Hello, $1!',\n        'items-count': '$1 item(s) found.',\n    }\n});\n\n// Translating a simple message\nconsole.log(banana.i18n('greet-user', 'Alice')); // Output: Hello, Alice!\n\n// Translating with variables\nconsole.log(banana.i18n('items-count', 5)); // Output: 5 item(s) found.\n\n// Changing the language dynamically\nbanana.setLocale('fr');\nbanana.load({\n    'greet-user': 'Bonjour, $1!',\n    'items-count': '$1 article(s) trouvé(s).',\n});\n\nconsole.log(banana.i18n('greet-user', 'Alice')); // Output: Bonjour, Alice!\n```\n\n### JavaScript\n\nFor usage in JavaScript, please check the files under the `demo` folder after building the distribution files by running `npm run build`.\n\n## Demo\n\nSee the library in action: https://wikimedia.github.io/banana-i18n/demo/\n\nRelated code can be found under the `demo` folder.\n\n## Developer Documentation\n### Banana File format\n\nThe message files are json formatted. As a convention, you can have a folder named i18n inside your source code. For each language or locale, have a file named like languagecode.json.\n\nExample:\n\n```\nApp\n    |--src\n    |--doc\n    |--i18n\n        |--ar.json\n        |--de.json\n        |--en.json\n        |--he.json\n        |--hi.json\n        |--fr.json\n        |--qqq.json\n```\n\nA simple en.json file example is given below\n\n```json\n{\n    \"@metadata\": {\n        \"authors\": [\n            \"Alice\",\n            \"David\",\n            \"Santhosh\"\n        ],\n        \"last-updated\": \"2012-09-21\",\n        \"locale\": \"en\",\n        \"message-documentation\": \"qqq\",\n        \"AnotherMetadata\": \"AnotherMedatadataValue\"\n    },\n    \"appname-title\": \"Example Application\",\n    \"appname-sub-title\": \"An example application with jquery.i18n\",\n    \"appname-header-introduction\": \"Introduction\",\n    \"appname-about\": \"About this application\",\n    \"appname-footer\": \"Footer text\"\n}\n```\n\nThe json file should be a valid json. The ```@metadata``` holds all kind of data that are not messages. You can store author information, copyright, updated date or anything there.\n\nMessages are key-value pairs. It is a good convention to prefix your appname to message keys to make the messages unique. It acts as the namespace for the message keys. It is also a good convention to have the message keys with ```-``` separated words, all in lower case.\n\nIf you are curious to see some real jquery.i18n message file from other projects:\n\n- message files of MediaWiki https://github.com/wikimedia/mediawiki-core/tree/master/languages/i18n\n- message files from jquery.uls project https://github.com/wikimedia/jquery.uls/blob/master/i18n\n\n### Loading the messages\n\nThe localized message should be loaded before using .i18n() method. This can be done as follows:\n\n#### Using the constructor\n\n```javascript\nconst banana = new Banana('es',{\n  messages: {\n   'key-1': 'Localized message'\n  }\n})\n```\n\n#### Load the messages for a locale\n\nAfter the initialization,\n\n```javascript\nconst messages = {\n  'message-key-1': 'Localized message 1',\n  // Rest of the messages\n};\nbanana.load(messages, 'es' );\n```\n\n#### Load the messages for many locales at once\n\n\u003e While it is possible to store all translations in a single file, we recommend using separate files for each language.\n\u003e It simplifies tracking changes via VCS and enables multiple translators or teams to work on different language files simultaneously without conflicts. \n\u003e Additionally, using separate files allows loading only the translations for the currently selected language, improving performance by avoiding the need\n\u003e to load all translations.\n\u003e \n\u003e Having one translation file per language is a requirement to add the project for translation on [translatewiki.net](https://translatewiki.net)\n\nTo load all messages for all locales at once, you can do this as follows. Here the messages are keyed by locale.\n\n```javascript\nconst messages = {\n  'es': {\n    'message-key-1': 'Localized message 1 for es',\n    // Rest of the messages for es\n  },\n  'ru': {\n    'message-key-1': 'Localized message 1 for ru',\n    // Rest of the messages for ru\n  }\n};\nbanana.load(messages); // Note that the locale parameter is missing here\n```\n\nDepeding on your application, the messages can be fetched from a server or a file system. Here is an example that fetches the localized messages json file.\n\n```javascript\nfetch('i18n/es.json').then((response) =\u003e response.json()).then((messages) =\u003e {\n  banana.load(messages, 'es');\n});\n```\n\nYou may load the messages in parts too. That means, you can use the `banana.load(message_set1, 'es')` and later `banana.load(message_set2, 'es')`. Both of the messages will be merged to the locale. If message_2 has the same key of message_set1, the last message loaded wins.\n\n### Setting the locale\n\nThe constructor for Banana class accepts the locale\n\n```javascript\nconst banana = new Banana('es')\n```\n\nOnce the banana i18n is initialized you can change the locale using setLocale method\n\n```javascript\nbanana.setLocale('es'); // Change to new locale\n```\n\nAll .i18n() calls will set the message for the new locale from there onwards.\n\n### Fallback\n\nIf a particular message is not localized for locale, but localized for a fallback locale(defined in src/languages/fallbacks.json),\nthe .i18n() method will return that. By default English is the final fallback language. But this configurable using `finalFallback` option. Example: `new Banana('ru', {finalFallback:'es' })`\n\n### Placeholders\n\nMessages take parameters. They are represented by $1, $2, $3, … in the message texts, and replaced at run time. Typical parameter values are numbers (Example: \"Delete 3 versions?\"), or user names (Example: \"Page last edited by $1\"), page names, links, and so on, or sometimes other messages.\n\n```javascript\nconst message = \"Welcome, $1\";\nbanana.i18n(message, 'Alice'); // This gives \"Welcome, Alice\"\n```\n\n### Plurals\n\nTo make the syntax of sentence correct, plural forms are required. jquery.i18n support plural forms in the message using the syntax `{{PLURAL:$1|pluralform1|pluralform2|...}}`\n\nFor example:\n\n```javascript\nconst message = \"Found $1 {{PLURAL:$1|result|results}}\";\nbanana.i18n(message, 1); // This gives \"Found 1 result\"\nbanana.i18n(message, 4); // This gives \"Found 4 results\"\n```\n\nNote that {{PLURAL:...}} is not case sensitive. It can be {{plural:...}} too.\n\nIn case of English, there are only 2 plural forms, but many languages use more than 2 plural forms. All the plural forms can be given in the above syntax, separated by pipe(|). The number of plural forms for each language is defined in [CLDR](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html). You need to provide all those plural forms for a language.\n\nFor example, English has 2 plural forms and the message format will look like `{{PLURAL:$1|one|other}}`. for Arabic there are 6 plural forms and format will look like `{{PLURAL:$1|zero|one|two|few|many|other}}`.\n\nYou cannot skip a plural form from the middle or beginning. However, you can skip from end. For example, in Arabic, if the message is like\n`{{PLURAL:$1|A|B}}`, for 0, A will be used, for numbers that fall under one, two, few, many, other categories B will be used.\n\nIf there is an explicit plural form to be given for a specific number, it is possible with the following syntax\n\n```javascript\nconst message = 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.';\nbanana.i18n(message, 4 ); // Gives \"Box has 4 eggs.\"\nbanana.i18n(message, 12 ); // Gives \"Box has a dozen eggs.\"\n```\n\n### Gender\n\nSimilar to plural, depending on gender of placeholders, mostly user names, the syntax changes dynamically. An example in English is \"Alice changed her profile picture\" and \"Bob changed his profile picture\". To support this {{GENDER...}} syntax can be used as shown in example\n\n```javascript\nconst message = \"$1 changed {{GENDER:$2|his|her}} profile picture\";\nbanana.i18n(message, 'Alice', 'female' ); // This gives \"Alice changed her profile picture\"\nbanana.i18n(message, 'Bob', 'male' ); // This gives \"Bob changed his profile picture\"\n```\n\nNote that {{GENDER:...}} is not case sensitive. It can be {{gender:...}} too.\n\n### Grammar\n\n```javascript\nconst banana = new Banana( 'fi' );\n\nconst message = \"{{grammar:genitive|$1}}\";\n\nbanana.i18n(message, 'talo' ); // This gives \"talon\"\n\nbanana.locale = 'hy'; // Switch to locale Armenian\nbanana.i18n(message, 'Մաունա'); // This gives \"Մաունայի\"\n```\n\n### Directionality-safe isolation\n\nTo avoid BIDI corruption that looks like \"(Foo_(Bar\", which happens when a string is inserted into a context with the reverse directionality, you can use `{{bidi:…}}`. Directionality-neutral characters at the edge of the string can get wrongly interpreted by the BIDI algorithm. This would let you embed your substituted string into a new BIDI context, //e.g.//:\n\n   \"`Shalom, {{bidi:$1}}, hi!`\"\n\nThe embedded context's directionality is determined by looking at the argument for `$1`, and then explicitly inserted into the Unicode text, ensuring correct rendering (because then the bidi algorithm \"knows\" the argument text is a separate context).\n\n### Wiki style links\n\nThe message can use [MediaWiki link syntax](https://www.mediawiki.org/wiki/Help:Links). By default this is disabled. To enable support for this, pass `wikilinks=true` option to `Banana` constructor. Example:\n\n```\nnew Banana('es', { wikilinks: true } )\n```\n\nThe original wiki links markup is elaborate, but here we only support simple syntax.\n\n* Internal links:  `[[pageTitle]]`  or `[[pageTitle|displayText]]`. For example `[[Apple]]` gives `\u003ca href=\"./Apple\" title=\"Apple\"\u003eApple\u003c/a\u003e`.\n* External links: `[https://example.com]` or `[https://example.com display text]`\n\n### Extending the parser\n\nFollowing example illustrates extending the parser to support more parser plugins\n\n```js\nconst banana = new Banana('en');\nbanana.registerParserPlugin('sitename', () =\u003e {\n  return 'Wikipedia';\n});\nbanana.registerParserPlugin('link', (nodes) =\u003e {\n  return '\u003ca href=\"' + nodes[1] + '\"\u003e' + nodes[0] + '\u003c/a\u003e';\n});\n```\n\nThis will parse the message\n```js\nbanana.i18n('{{link:{{SITENAME}}|https://en.wikipedia.org}}');\n```\nto\n\n```\n\u003ca href=\"https://en.wikipedia.org\"\u003eWikipedia\u003c/a\u003e\n```\n\n### Message documentation\n\nThe message keys and messages won't give a enough context about the message being translated to the translator. Whenever a developer adds a new message, it is a usual practice to document the message to a file named qqq.json\nwith same message key.\n\nExample qqq.json:\n\n```json\n{\n    \"@metadata\": {\n        \"authors\": [\n            \"Developer Name\"\n        ]\n    },\n    \"appname-title\": \"Application name. Transliteration is recommended\",\n    \"appname-sub-title\": \"Brief explanation of the application\",\n    \"appname-header-introduction\": \"Text for the introduction header\",\n    \"appname-about\": \"About this application text\",\n    \"appname-footer\": \"Footer text\"\n}\n\n```\n\nIn MediaWiki and its hundreds of extensions, message documentation is a strictly followed practice. There is a grunt task to check whether all messages are documented or not. See https://www.npmjs.org/package/grunt-banana-checker\n\n### Translation\n\nTo translate the banana-i18n based application, depending on the expertise of the translator, there are multiple ways.\n\n- Editing the json files directly - Suitable for translators with technical background. Also suitable if your application is small and you want to work with only a small number of languages\n- Providing a translation interface along with your application: Suitable for proprietary or private applications with significant amount of translators\n- Using open source translation platforms like translatewiki.net. The MediaWiki and jquery.uls from previous examples use translatewiki.net for crowdsourced message translation. Translatewiki.net can update your code repo at regular intervals with updated translations. Highly recommended if your application is opensource and want it to be localized to as many as languages possible with maximum number of translators.\n\n### Frameworks and other programming languages\n\n* React bindings for banana-i18n  https://www.npmjs.com/package/@wikimedia/react.i18n\n* A Banana-i18n wrapper to support localization in Vue.js https://www.npmjs.com/package/vue-banana-i18n\n* Python version of this library: https://pypi.org/project/banana-i18n/\n* Python Flask integration https://pypi.org/project/Flask-Banana/\n\n## Thanks\n\nThis project is based on [jquery.i18n](github.com/wikimedia/jquery.i18n) library maintained by Wikimedia Foundation. Most of the internationalization related logic comes from that project. In Banana-i18n, jquery dependency was removed and the library was modernized to use in modern web applications. Contributors of jquery.i18n are greatly acknowledged and listed in AUTHORS.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikimedia%2Fbanana-i18n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwikimedia%2Fbanana-i18n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikimedia%2Fbanana-i18n/lists"}