{"id":13509695,"url":"https://github.com/formatjs/intl-messageformat","last_synced_at":"2025-03-30T13:32:40.714Z","repository":{"id":12305142,"uuid":"14936840","full_name":"formatjs/intl-messageformat","owner":"formatjs","description":"[MIGRATED] Format a string with placeholders, including plural and select support to create localized messages.","archived":true,"fork":false,"pushed_at":"2019-05-22T17:48:05.000Z","size":1787,"stargazers_count":530,"open_issues_count":0,"forks_count":67,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-03-27T20:10:24.903Z","etag":null,"topics":["internationalization","javascript","localization","web"],"latest_commit_sha":null,"homepage":"http://formatjs.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/formatjs.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}},"created_at":"2013-12-04T21:48:45.000Z","updated_at":"2024-08-26T20:40:16.000Z","dependencies_parsed_at":"2022-07-12T15:04:40.783Z","dependency_job_id":null,"html_url":"https://github.com/formatjs/intl-messageformat","commit_stats":null,"previous_names":["yahoo/intl-messageformat"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-messageformat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-messageformat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-messageformat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-messageformat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/formatjs","download_url":"https://codeload.github.com/formatjs/intl-messageformat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245967658,"owners_count":20701877,"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":["internationalization","javascript","localization","web"],"created_at":"2024-08-01T02:01:11.606Z","updated_at":"2025-03-30T13:32:40.679Z","avatar_url":"https://github.com/formatjs.png","language":"TypeScript","readme":"# This repo was migrated to the [monorepo](https://github.com/formatjs/formatjs/tree/master/packages/intl-messageformat)\n\nIntl MessageFormat\n==================\n\nFormats ICU Message strings with number, date, plural, and select placeholders to create localized messages.\n\n[![npm Version][npm-badge]][npm]\n[![Build Status][travis-badge]][travis]\n[![Dependency Status][david-badge]][david]\n\n\n![gzip size](https://img.badgesize.io/formatjs/intl-messageformat/master/dist/intl-messageformat.min.js?compression=gzip\u0026label=core+gzip+size)\n\n[![Sauce Test Status][sauce-badge]][sauce]\n\nOverview\n--------\n\n### Goals\n\nThis package aims to provide a way for you to manage and format your JavaScript app's string messages into localized strings for people using your app. You can use this package in the browser and on the server via Node.js.\n\nThis implementation is based on the [Strawman proposal][strawman], but there are a few places this implementation diverges.\n\n_Note: This `IntlMessageFormat` API may change to stay in sync with ECMA-402, but this package will follow [semver][]._\n\n### How It Works\n\nMessages are provided into the constructor as a `String` message, or a [pre-parsed AST][parser] object.\n\n```js\nvar msg = new IntlMessageFormat(message, locales, [formats]);\n```\n\nThe string `message` is parsed, then stored internally in a compiled form that is optimized for the `format()` method to produce the formatted string for displaying to the user.\n\n```js\nvar output = msg.format(values);\n```\n\n### Common Usage Example\n\nA very common example is formatting messages that have numbers with plural labels. With this package you can make sure that the string is properly formatted for a person's locale, e.g.:\n\n```js\nvar MESSAGES = {\n    'en-US': {\n        NUM_PHOTOS: 'You have {numPhotos, plural, ' +\n            '=0 {no photos.}' +\n            '=1 {one photo.}' +\n            'other {# photos.}}'\n    },\n\n    'es-MX': {\n        NUM_PHOTOS: 'Usted {numPhotos, plural, ' +\n            '=0 {no tiene fotos.}' +\n            '=1 {tiene una foto.}' +\n            'other {tiene # fotos.}}'\n    }\n};\n\nvar output;\n\nvar enNumPhotos = new IntlMessageFormat(MESSAGES['en-US'].NUM_PHOTOS, 'en-US');\noutput = enNumPhotos.format({numPhotos: 1000});\nconsole.log(output); // =\u003e \"You have 1,000 photos.\"\n\nvar esNumPhotos = new IntlMessageFormat(MESSAGES['es-MX'].NUM_PHOTOS, 'es-MX');\noutput = esNumPhotos.format({numPhotos: 1000});\nconsole.log(output); // =\u003e \"Usted tiene 1,000 fotos.\"\n```\n\n### Message Syntax\n\nThe message syntax that this package uses is not proprietary, in fact it's a common standard message syntax that works across programming languages and one that professional translators are familiar with. This package uses the **[ICU Message syntax][ICU]** and works for all [CLDR languages][CLDR] which have pluralization rules defined.\n\n### Features\n\n* Uses industry standards: [ICU Message syntax][ICU] and [CLDR locale data][CLDR].\n\n* Supports **plural**, **select**, and **selectordinal** message arguments.\n\n* Formats numbers and dates/times in messages using [`Intl.NumberFormat`][Intl-NF] and [`Intl.DateTimeFormat`][Intl-DTF], respectively.\n\n* Optimized for repeated calls to an `IntlMessageFormat` instance's `format()` method.\n\n* Supports defining custom format styles/options.\n\n* Supports escape sequences for message syntax chars, e.g.: `\"\\\\{foo\\\\}\"` will output: `\"{foo}\"` in the formatted output instead of interpreting it as a `foo` argument.\n\n\nUsage\n-----\n\n### Modern `Intl` Dependency\n\nThis package assumes that the [`Intl`][Intl] global object exists in the runtime. `Intl` is present in all modern browsers (IE11+) and Node (with full ICU). The `Intl` methods we rely on are:\n\n1. `Intl.NumberFormat` for number formatting (can be polyfilled using [Intl.js][])\n2. `Intl.DateTimeFormat` for date time formatting (can be polyfilled using [Intl.js][])\n3. `Intl.PluralRules` for plural/ordinal formatting (can be polyfilled using [intl-pluralrules][])\n\n### Loading Intl MessageFormat in a browser\n\n```html\n\u003cscript src=\"intl-messageformat/intl-messageformat.min.js\"\u003e\u003c/script\u003e\n```\n\n### Loading Intl MessageFormat in Node.js\n\nSimply `require()` this package:\n\n```js\nvar IntlMessageFormat = require('intl-messageformat');\n```\n\n**NOTE: Your Node has to include [full ICU](https://nodejs.org/api/intl.html)**\n\n### Public API\n\n#### `IntlMessageFormat` Constructor\nTo create a message to format, use the `IntlMessageFormat` constructor. The constructor takes three parameters:\n\n - **message** - _{String | AST}_ - String message (or pre-parsed AST) that serves as formatting pattern.\n\n - **locales** - _{String | String[]}_ - A string with a BCP 47 language tag, or an array of such strings. If you do not provide a locale, the default locale will be used. When an array of locales is provided, each item and its ancestor locales are checked and the first one with registered locale data is returned. **See: [Locale Resolution](#locale-resolution) for more details.**\n\n - **[formats]** - _{Object}_ - Optional object with user defined options for format styles.\n\n```js\nvar msg = new IntlMessageFormat('My name is {name}.', 'en-US');\n```\n\n#### Locale Resolution\n\n`IntlMessageFormat` uses `Intl.NumberFormat.supportedLocalesOf()` to determine which locale data to use based on the `locales` value passed to the constructor. The result of this resolution process can be determined by call the `resolvedOptions()` prototype method.\n\n#### `resolvedOptions()` Method\n\nThis method returns an object with the options values that were resolved during instance creation. It currently only contains a `locale` property; here's an example:\n\n```js\nvar msg = new IntlMessageFormat('', 'en-us');\nconsole.log(msg.resolvedOptions().locale); // =\u003e \"en-US\"\n```\n\nNotice how the specified locale was the all lower-case value: `\"en-us\"`, but it was resolved and normalized to: `\"en-US\"`.\n\n#### `format(values)` Method\n\nOnce the message is created, formatting the message is done by calling the `format()` method on the instance and passing a collection of `values`:\n\n```js\nvar output = msg.format({name: \"Eric\"});\nconsole.log(output); // =\u003e \"My name is Eric.\"\n```\n\n_Note: A value **must** be supplied for every argument in the message pattern the instance was constructed with._\n\n#### User Defined Formats\n\nDefine custom format styles is useful you need supply a set of options to the underlying formatter; e.g., outputting a number in USD:\n\n```js\nvar msg = new IntlMessageFormat('The price is: {price, number, USD}', 'en-US', {\n    number: {\n        USD: {\n            style   : 'currency',\n            currency: 'USD'\n        }\n    }\n});\n\nvar output = msg.format({price: 100});\nconsole.log(output); // =\u003e \"The price is: $100.00\"\n```\n\nIn this example, we're defining a `USD` number format style which is passed to the underlying `Intl.NumberFormat` instance as its options.\n\n\nExamples\n--------\n\n### Plural Label\n\nThis example shows how to use the [ICU Message syntax][ICU] to define a message that has a plural label; e.g., ``\"You have 10 photos\"``:\n\n```\nYou have {numPhotos, plural,\n    =0 {no photos.}\n    =1 {one photo.}\n    other {# photos.}\n}\n```\n\n```js\nvar MESSAGES = {\n    photos: '...', // String from code block above.\n    ...\n};\n\nvar msg = new IntlMessageFormat(MESSAGES.photos, 'en-US');\n\nconsole.log(msg.format({numPhotos: 0}));    // =\u003e \"You have no photos.\"\nconsole.log(msg.format({numPhotos: 1}));    // =\u003e \"You have one photo.\"\nconsole.log(msg.format({numPhotos: 1000})); // =\u003e \"You have 1,000 photos.\"\n```\n\n_Note: how when `numPhotos` was `1000`, the number is formatted with the correct thousands separator._\n\n\nLicense\n-------\n\nThis software is free to use under the Yahoo! Inc. BSD license.\nSee the [LICENSE file][LICENSE] for license text and copyright information.\n\n\n[npm]: https://www.npmjs.org/package/intl-messageformat\n[npm-badge]: https://img.shields.io/npm/v/intl-messageformat.svg?style=flat-square\n[david]: https://david-dm.org/formatjs/intl-messageformat\n[david-badge]: https://img.shields.io/david/formatjs/intl-messageformat.svg?style=flat-square\n[travis]: https://travis-ci.org/formatjs/intl-messageformat\n[travis-badge]: https://img.shields.io/travis/formatjs/intl-messageformat/master.svg?style=flat-square\n[sauce]: https://saucelabs.com/u/intl-messageformat\n[sauce-badge]: https://saucelabs.com/browser-matrix/intl-messageformat.svg\n[strawman]: http://wiki.ecmascript.org/doku.php?id=globalization:messageformatting\n[parser]: https://github.com/formatjs/intl-messageformat-parser\n[ICU]: http://userguide.icu-project.org/formatparse/messages\n[CLDR]: http://cldr.unicode.org/\n[Intl]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl\n[Intl-NF]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat\n[Intl-DTF]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat\n[Intl-Node]: https://github.com/joyent/node/issues/6371\n[Intl.js]: https://github.com/andyearnshaw/Intl.js\n[rawgit]: https://rawgit.com/\n[semver]: http://semver.org/\n[LICENSE]: https://github.com/formatjs/intl-messageformat/blob/master/LICENSE\n[intl-pluralrules]: https://github.com/eemeli/intl-pluralrules\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fformatjs%2Fintl-messageformat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fformatjs%2Fintl-messageformat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fformatjs%2Fintl-messageformat/lists"}