Василиса▶ Я жду вашего обращения. Что Вы хотите узнать?
Логотип
GitHub - wikimedia/jquery.i18n: ����jQuery based internationalization library Sign up Why GitHub? Features Mobile Actions Codespaces Packages Security Code review Project management Integrations GitHub Sponsors Customer stories Security Team Enterprise Explore Explore GitHub Learn and contribute Topics Collections Trending Learning Lab Open source guides Connect with others The ReadME Project Events Community forum GitHub Education GitHub Stars program Marketplace Pricing Plans Compare plans Contact Sales Nonprofit Education Sign in Sign up {{ message }} / jquery.i18n Notifications Star Fork View license 573 stars 126 forks Star Notifications Code Issues 47 Pull requests 7 Actions Security Insights More Code Issues Pull requests Actions Security Insights masterSwitch branches/tags Nothing to show {{ refName }} View all branches Nothing to show {{ refName }} View all tags 3 branches 9 tags Go to file Code Clone

Use Git or checkout with SVN using the web URL.

Work fast with our official CLI. Learn more .

Open with GitHub Desktop Download ZIP Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio

If nothing happens, download the GitHub extension for Visual Studio and try again.

Latest commit @amire80 amire80 Merge pull request #220 from wikimedia/dependabot/npm_and_yarn/lodash… 564f66c Merge pull request #220 from wikimedia/dependabot/npm_and_yarn/lodash… …-4.17.20 build(deps): bump lodash from 4.17.15 to 4.17.20564f66cGit stats 353 commits Files Permalink Failed to load latest commit information. TypeNameLatest commit messageCommit time demo Remove String.prototype overriding libs Update CLDRPluralRuleParser submodule to v1.2.0 src Change RegExp syntax rule to satisfy eslint test Support loading combined message file from URL .eslintrc.json build: Update eslint config .gitignore Updated gitignore file .gitmodules Fix the path to qunit.js and qunit.css .mailmap build: Add a .mailmap file so that `git shortlog` is cleaner .travis.yml Update node version to 13 in Travis configuration CODE_OF_CONDUCT.md Update CODE_OF_CONDUCT.md CREDITS List major contributors in CREDITS file GPL-LICENSE Use the official plain-text version of the GPL Gruntfile.js build: Update eslint config MIT-LICENSE Add license and credits files README.md Update README: Add npm badge, highlight banana-i18n package-lock.json build(deps): bump lodash from 4.17.15 to 4.17.20 package.json Update devDependencies packages README.md jQuery.i18n npm

NOTE: For jquery independent version of this library, see https://github.com/wikimedia/banana-i18n

jQuery.i18n is a jQuery based Javascript internationalization library. It helps you to internationalize your web applications easily.

This is a project by Wikimedia foundation's Language Engineering team and used in some of the Wikimedia Foundation projects like Universal Language Selector.

The jquery.i18n library uses a json based localization file format, "banana", which is used as the localization file format for MediaWiki and other projects.

FeaturesSimple file format - JSON. Easily readable for humans and machines.Author and metadata information is not lost anywhere. There are other file formats using comments to store this.Uses MediaWiki convention for placeholders. Easily readable and proven convention. Example: There are $1 carsSupports plural conversion without using extra messages for all plural forms. Plural rule handling is done using CLDR. Covers a wide range of languagesSupports gender. By passing the gender value, you get correct sentences according to gender.Supports grammar forms. jquery.i18n has a basic but extensible grammar conversion supportFallback chains for all languages.Data api- the message key. Example: <li data-i18n="message-key"></li>.Dynamic change of interface language without refreshing a webpage.Nestable grammar, plural, gender support. These constructs can be nested to any arbitrary level for supporting sophisticated message localizationMessage documentation through special language code qqqExtensible message parser to add or customize magic words in the messages. Example: {sitename} or linkQuick startgit clone https://github.com/wikimedia/jquery.i18n.git cd jquery.i18n git submodule update --initTestingnpm install

To run tests locally, run npm test , and this will run the tests.

Message File Format

The 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.

Example:

App |--src |--doc |--i18n |--ar.json |--de.json |--en.json |--he.json |--hi.json |--fr.json |--qqq.json

A simple en.json file example is given below

{ "@metadata": { "authors": [ "Alice", "David", "Santhosh" ], "last-updated": "2012-09-21", "locale": "en", "message-documentation": "qqq", "AnotherMetadata": "AnotherMedatadataValue" }, "appname-title": "Example Application", "appname-sub-title": "An example application with jquery.i18n", "appname-header-introduction": "Introduction", "appname-about": "About this application", "appname-footer": "Footer text" }

The 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.

Messages 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.

If you are curious to see some real jquery.i18n message file from other projects:

message files of MediaWiki https://github.com/wikimedia/mediawiki-core/tree/master/languages/i18n message files from jquery.uls project https://github.com/wikimedia/jquery.uls/blob/master/i18n Single message file for all languages

There are some alternate message file formats supported for different use cases. If your application is not big, and want all the translation in a single file, you can have it as shown in the below example:

{ "@metadata": { "authors": [ "Alice", "David", "Santhosh" ], "last-updated": "2012-09-21", "locale": "en", "message-documentation": "qqq", "AnotherMetadata": "AnotherMedatadataValue" }, "en": { "appname-title": "Example Application", "appname-sub-title": "An example application with jquery.i18n", "appname-header-introduction": "Introduction", "appname-about": "About this application", "appname-footer": "Footer text" }, "ml": { "appname-title": "������������‍ �������", "appname-sub-title": "jquery.i18n ������������� ������������‍ �������", "appname-header-introduction": "�����", "appname-about": "� �������������������", "appname-footer": "��������������" } }

Here the json file contains language code as key-value and messagekey-message pairs as the value for all language pairs. You can choose this format or per-language file formats depending on your use case. Per-language files are more convenient for collaboration, version controlling, scalability, etc.

In this approach, it is also possible to give a file name as the value of language code.

{ "@metadata": { "authors": [ "Alice", "David", "Santhosh" ], "last-updated": "2012-09-21", "locale": "en", "message-documentation": "qqq", "AnotherMetadata": "AnotherMedatadataValue" }, "en": { "appname-title": "Example Application", "appname-sub-title": "An example application with jquery.i18n", "appname-header-introduction": "Introduction", "appname-about": "About this application", "appname-footer": "Footer text" }, "ml": "path/to/ml.json" }Translation

To translate the jquery.i18n application, depending on the expertise of the translator, there are multiple ways.

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 languagesProviding a translation interface along with your application: Suitable for proprietary or private applications with significant amount of translatorsUsing 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.UsageSwitching locale

While initializing the jquery.i18n , the locale for the page can be given using the locale option. For example

$.i18n({locale: 'he'// Locale is Hebrew});

In case locale option is not given, jquery.i18n plugin will use the language attribute given for the html tag. For example

<htmllang="he" dir="rtl">

In this case, the locale will be he(Hebrew). If that lang attribute is also missing, it will try to use the locale specified by the browser.

It is possible to switch to another locale after plugin is initialized. See below example:

$.i18n({locale: 'he'// Locale is Hebrew});$.i18n('message-hello');// This will give the Hebrew translation of message key `message-hello`.$.i18n().locale='ml';// Now onwards locale is 'Malayalam'$.i18n('message-hello');// This will give the Malayalam translation of message key `message-hello`.Message Loading

JSON formatted messages can be loaded to the plugin using multiple ways.

Dynamic loading using load method.

Following example shows loading messages for two locales- localex, and localey. Here localex and localey are just examples. They should be valid IS0 639 language codes(eg: en, ml, hi, fr, ta etc)

$.i18n().load({'localex' : {'message-key1' : 'message1'// Message for localex.},'localey' : {'message-key1' : 'message1'}});

If we want to load the messages for a specific locale, it can be done like this:

$.i18n().load({'message-hello': 'Hello World','message-welcome': 'Welcome'},'en');

Note the second argument for the load method. It should be a valid language code.

It is also possible to refer messages from an external URL. See below example

$.i18n().load({en: {'message-hello': 'Hello World','message-welcome': 'Welcome'},hi: 'i18n/messages-hi.json',// Messages for Hindide: 'i18n/messages-de.json'});

Messages for a locale can be also loaded in parts. Example

$.i18n().load({en: {'message-hello': 'Hello World','message-welcome': 'Welcome'}});$.i18n().load({// This does not remove the previous messages.en: {'message-header' : 'Header','message-footer' : 'Footer',// This will overwrite message-welcome message'message-welcome' : 'Welcome back'}});

Since it is desirable to render interface messages instantly and not after a delay of loading the message files from a server, make sure that the messages are present at client side before using jQuery.i18n.

The library should expose an API to load an object containing key-value pair of messages. Example: $.i18n.load(data) . This will return a jQuery.Promise .

jquery.i18n plugin

The jQuery plugin defines $.i18n() and $.fn.i18n()

$.i18n('message-key-sample1');$.i18n('message-key-sample1');$.i18n('Found $1 {{plural:$1|result|results}}',10);// Message key itself is message text$.i18n('Showing $1 out of $2 {{plural:$2|result|results}}',5,100);$.i18n('User X updated {{gender|his|her}} profile','male');$('#foo').i18n();// to translate the element matching jquery selector based on data-i18n keyData API

It is possible to display localized messages without any custom JavaScript. For the HTML tags, add an attribute data-i18n with value as the message key. Example:

<lidata-i18n="message-key"></li>.

It is also possible to have the above li node with fallback text already in place.

<lidata-i18n="message-key">Fallback text</li>

The framework will place the localized message corresponding to message-key as the text value of the node. Similar to $('selector').i18n( ... ). This will not work for dynamically created elements.

Note that if data-i18n contains html markup, that html will not be used as the element content, instead, the text version will be used. But if the message key is prefixed with [html] , the element's html will be changed. For example <li data-i18n="[html]message-key">Fallback html</li> , in this if the message-key has a value containing HTML markup, the <li> tags html will be replaced by that html.

If you want to change the html of the element, you can also use: $(selector).html($.i18n(messagekey))

Examples

See https://thottingal.in/projects/js/jquery.i18n/demo/

Message formatPlaceholders

Messages 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.

varmessage="Welcome, $1";$.i18n(message,'Alice');// This gives "Welcome, Alice"Plurals

To 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|...}}

For example:

varmessage="Found $1 {{PLURAL:$1|result|results}}";$.i18n(message,1);// This gives "Found 1 result"$.i18n(message,4);// This gives "Found 4 results"

Note that {{PLURAL:...}} is not case sensitive. It can be {{plural:...}} too.

In 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 . You need to provide all those plural forms for a language. Please note that many languages will require the inclusion of CLDRPluralRuleParser.js ( from here ) as well as this project's own files to work properly.

For 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}} .

You 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 {{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.

If there is an explicit plural form to be given for a specific number, it is possible with the following syntax

var message = 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.'; $.i18n(message, 4 ); // Gives "Box has 4 eggs." $.i18n(message, 12 ); // Gives "Box has a dozen eggs." Gender

Similar 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

varmessage="$1 changed {{GENDER:$2|his|her}} profile picture";$.i18n(message,'Alice','female');// This gives "Alice changed her profile picture"$.i18n(message,'Bob','male');// This gives "Bob changed his profile picture"

Note that {{GENDER:...}} is not case sensitive. It can be {{gender:...}} too.

Grammar$.i18n({locale: 'fi'});varmessage="{{grammar:genitive|$1}}";$.i18n(message,'talo');// This gives "talon"$.i18n().locale='hy';// Switch to locale Armenian$.i18n(message,'Մաունա');// This gives "Մաունայի"Directionality-safe isolation

To 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.//:

" Shalom, {{bidi:$1}}, hi! "

The 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).

Fallback

The plugin takes an option 'fallback' with the default value 'en'. The library reuses the fallback data available in MediaWiki for calculating the language fallbacks. Fallbacks are used when a message key is not found in a locale. Example fallbacks: sa->hi->en or tt->tt-cyrl->ru.

See jquery.i18n.fallbacks.js in the source.

Magic word supportFor plural, gender and grammar support, MediaWiki template-like syntax - {{...}} will be used.There will be a default implementation for all these in $.i18n.language['default']The plural, gender and grammar methods in $.i18n.language[ 'default' ] can be overridden or extended in $.i18n.language['languageCode'].Language-specific rules about Gender and Grammar can be written in languages/langXYZ.js filesPlural forms will be dynamically calculated using the CLDR plural parser.Extending the parser

Following example illustrates extending the parser to support more magic words

$.extend($.i18n.parser.emitter,{// Handle SITENAME keywordssitename: function(){return'Wikipedia';},// Handle LINK keywordslink: function(nodes){return'<a href="'+nodes[1]+'">'+nodes[0]+'</a>';}});

This will parse the message

$.i18n('{{link:{{SITENAME}}|https://en.wikipedia.org}}');

to

<ahref="https://en.wikipedia.org">Wikipedia</a>Message documentation

The 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 with same message key.

Example qqq.json:

{ "@metadata": { "authors": [ "Developer Name" ] }, "appname-title": "Application name. Transliteration is recommended", "appname-sub-title": "Brief explanation of the application", "appname-header-introduction": "Text for the introduction header", "appname-about": "About this application text", "appname-footer": "Footer text" }

In 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

AboutTopics javascript i18n intl ResourcesLicense View license Releases 9
V1.0.7 Latest
+ 8 releases Packages No packages published Used by 16
  • @wbstack
  • @ElMulot
  • @erfurtjohn
  • @4ch1m
  • @gaybro8777
  • @Huessenbergnetz
  • @ethiopicist
  • @kurraraghu1234
+ 8
Contributors 31 @santhoshtr @amire80 @jdforrester @Nikerabbit @kartikm @siebrand @ricordisamoa @Krinkle @darkyen @jishnu7 @PreVaDu + 20 contributors Languages JavaScript 97.8% HTML 2.2% © 2021 GitHub, Inc. Terms Privacy Security Status Docs Contact GitHub Pricing API Training Blog About You signed in with another tab or window. to refresh your session.You signed out in another tab or window. to refresh your session.
© 2014-2021 ЯВИКС - все права защищены.
Наши контакты