{"id":13802072,"url":"https://github.com/formatjs/intl-relativeformat","last_synced_at":"2025-05-13T12:32:23.278Z","repository":{"id":20876605,"uuid":"24163710","full_name":"formatjs/intl-relativeformat","owner":"formatjs","description":"Formats JavaScript dates to relative time strings (e.g., \"3 hours ago\").","archived":true,"fork":false,"pushed_at":"2019-07-09T18:23:15.000Z","size":1987,"stargazers_count":213,"open_issues_count":1,"forks_count":41,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-02T04:28:43.879Z","etag":null,"topics":["formatjs","internationalization","javascript","nodejs","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":"CHANGELOG.md","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":"2014-09-17T21:50:23.000Z","updated_at":"2024-04-18T21:20:11.000Z","dependencies_parsed_at":"2022-08-30T11:32:15.413Z","dependency_job_id":null,"html_url":"https://github.com/formatjs/intl-relativeformat","commit_stats":null,"previous_names":["yahoo/intl-relativeformat"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-relativeformat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-relativeformat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-relativeformat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/formatjs%2Fintl-relativeformat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/formatjs","download_url":"https://codeload.github.com/formatjs/intl-relativeformat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253500060,"owners_count":21918094,"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":["formatjs","internationalization","javascript","nodejs","web"],"created_at":"2024-08-04T00:01:34.919Z","updated_at":"2025-05-13T12:32:23.248Z","avatar_url":"https://github.com/formatjs.png","language":"TypeScript","readme":"# THIS PACKAGE HAS BEEN DEPRECATED\n\n# Migration Guide\n\nThis package has deviated from the [`Intl.RelativeTimeFormat` spec](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) rather heavily. Therefore, we've deprecated this package and add [`@formatjs/intl-relativetimeformat](https://www.npmjs.com/package/@formatjs/intl-relativetimeformat) as the spec-compliant polyfill.\n\n1. All `units` (such as `day-short`) should be migrated similarly to:\n\n```ts\nnew IntlRelativeFormat('en', { units: 'second-short' }).format(\n  Date.now() - 1000\n);\n// will be\nnew Intl.RelativeTimeFormat('en', { style: 'short' }).format(-1, 'second');\n\nnew IntlRelativeFormat('en', { units: 'day-narrow' }).format(\n  Date.now() - 48 * 3600 * 1000\n);\n// will be\nnew Intl.RelativeTimeFormat('en', { style: 'narrow' }).format(-2, 'day');\n```\n\n2. `style: numeric` will become `numeric: always` per spec (which is also the default)\n\n```ts\nnew IntlRelativeFormat('en', {\n  units: 'second-short',\n  style: 'numeric'\n}).format(Date.now() - 1000);\n// will be\nnew Intl.RelativeTimeFormat('en', { style: 'short' }).format(-1, 'second');\n```\n\n```ts\nnew IntlRelativeFormat('en', { units: 'day-narrow', style: 'numeric' }).format(\n  Date.now() - 48 * 3600 * 1000\n);\n// will be\nnew Intl.RelativeTimeFormat('en', { style: 'narrow' }).format(-2, 'day');\n```\n\n3. `style: 'best fit'` is a little trickier but we have released `@formatjs/intl-utils` to ease the transition:\n\n```ts\nnew IntlRelativeFormat('en', { style: 'best fit' }).format(Date.now() - 1000);\n// will be\nimport { selectUnit } from '@formatjs/intl-utils';\nconst diff = selectUnit(Date.now() - 1000);\nnew Intl.RelativeTimeFormat('en', { numeric: 'auto' }).format(\n  diff.value,\n  diff.unit\n);\n```\n\n```ts\nnew IntlRelativeFormat('en', { style: 'best fit' }).format(\n  Date.now() - 48 * 3600 * 1000\n);\n// will be\nimport { selectUnit } from '@formatjs/intl-utils';\nconst diff = selectUnit(Date.now() - 48 * 3600 * 1000);\nnew Intl.RelativeTimeFormat('en', { numeric: 'auto' }).format(\n  diff.value,\n  diff.unit\n);\n```\n\n4. If you were using `options.now` in `format`, you can use `formatjs/intl-utils` to transition as well\n\n```ts\nnew IntlRelativeFormat('en', { style: 'best fit' }).format(Date.now() - 1000, {\n  now: Date.now() + 1000\n});\n// will be\nimport { selectUnit } from '@formatjs/intl-utils';\nconst diff = selectUnit(Date.now() - 1000, Date.now() + 1000);\nnew Intl.RelativeTimeFormat('en', { numeric: 'auto' }).format(\n  diff.value,\n  diff.unit\n);\n```\n\n```ts\nnew IntlRelativeFormat('en', { style: 'best fit' }).format(\n  Date.now() - 48 * 3600 * 1000,\n  { now: Date.now() + 1000 }\n);\n// will be\nimport { selectUnit } from '@formatjs/intl-utils';\nconst diff = selectUnit(Date.now() - 48 * 3600 * 1000, Date.now() + 1000);\nnew Intl.RelativeTimeFormat('en', { numeric: 'auto' }).format(\n  diff.value,\n  diff.unit\n);\n```\n\n# Intl RelativeFormat\n\nFormats JavaScript dates to relative time strings (e.g., \"3 hours ago\").\n\n[![npm Version][npm-badge]][npm]\n\n## Overview\n\n### Goals\n\nThis package aims to provide a way to format different variations of relative time. You can use this package in the browser and on the server via Node.js.\n\nThis implementation is very similar to [moment.js][], in concept, although it provides only formatting features based on the Unicode [CLDR][] locale data, an industry standard that supports more than 200 languages.\n\n### How It Works\n\n```js\nvar rf = new IntlRelativeFormat(locales, [options]);\n```\n\nThe `locales` can either be a single language tag, e.g., `\"en-US\"` or an array of them from which the first match will be used. `options` provides a way to control the output of the formatted relative time string.\n\n```js\nvar output = rf.format(someDate, [options]);\n```\n\n### Common Usage Example\n\nThe most common way to use this library is to construct an `IntlRelativeFormat` instance and reuse it many times for formatting different date values; e.g.:\n\n```js\nvar rf = new IntlRelativeFormat('en-US');\n\nvar posts = [\n  {\n    id: 1,\n    title: 'Some Blog Post',\n    date: new Date(1426271670524)\n  },\n  {\n    id: 2,\n    title: 'Another Blog Post',\n    date: new Date(1426278870524)\n  }\n];\n\nposts.forEach(function(post) {\n  console.log(rf.format(post.date));\n});\n// =\u003e \"3 hours ago\"\n// =\u003e \"1 hour ago\"\n```\n\n### Features\n\n- Style options for `\"best fit\"` (\"yesterday\") and `\"numeric\"` (\"1 day ago\") output based on thresholds.\n\n- Units options for always rendering in a particular unit; e.g. \"30 days ago\", instead of \"1 month ago\".\n\n- Ability to specify the \"now\" value from which the relative time is calculated, allowing `format()`.\n\n- Format output in relative time strings using [`Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)\n\n- Optimized for repeated calls to an `IntlRelativeFormat` instance's `format()` method.\n\n## Usage\n\n### `Intl` Dependency\n\nThis package assumes the following capabilities from `Intl`:\n\n1. [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules)\n2. [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)\n\nIf your environment does not support those, feel free to grab polyfills:\n\n1. https://www.npmjs.com/package/intl-pluralrules\n2. https://www.npmjs.com/package/@formatjs/intl-relativetimeformat\n\n### Loading IntlRelativeFormat in Node.js\n\nInstall package and polyfill:\n\n```bash\nnpm install intl-relativeformat --save\n```\n\nSimply `require()` this package:\n\n```js\nvar IntlRelativeFormat = require('intl-relativeformat');\nvar rf = new IntlRelativeFormat('en');\nvar output = rf.format(dateValue);\n```\n\n### Bundling IntlRelativeFormat with Browserify/Webpack/Rollup\n\nInstall package:\n\n```bash\nnpm install intl-relativeformat --save\n```\n\nSimply `require()` this package and the specific locales you wish to support in the bundle:\n\n```js\nvar IntlRelativeFormat = require('intl-relativeformat');\n```\n\n_Note: in Node.js, the data for all 200+ languages is loaded along with the library, but when bundling it with Browserify/Webpack, the data is intentionally ignored (see `package.json` for more details) to avoid blowing up the size of the bundle with data that you might not need._\n\n### Public API\n\n#### `IntlRelativeFormat` Constructor\n\nTo format a date to relative time, use the `IntlRelativeFormat` constructor. The constructor takes two parameters:\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- **[options]** - _{Object}_ - Optional object with user defined options for format styles.\n  **See: [Custom Options](#custom-options) for more details.**\n\n_Note: The `rf` instance should be enough for your entire application, unless you want to use custom options._\n\n#### Locale Resolution\n\n`IntlRelativeFormat` uses a locale resolution process similar to that of the built-in `Intl` APIs 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\nThe following are the abstract steps `IntlRelativeFormat` goes through to resolve the locale value:\n\n- If no extra locale data is loaded, the locale will _always_ resolved to `\"en\"`.\n\n- If locale data is missing for a leaf locale like `\"fr-FR\"`, but there _is_ data for one of its ancestors, `\"fr\"` in this case, then its ancestor will be used.\n\n- If there's data for the specified locale, then that locale will be resolved; i.e.,\n\n  ```js\n  var rf = new IntlRelativeFormat('en-US');\n  assert(rf.resolvedOptions().locale === 'en-US'); // true\n  ```\n\n- The resolved locales are now normalized; e.g., `\"en-us\"` will resolve to: `\"en-US\"`.\n\n_Note: When an array is provided for `locales`, the above steps happen for each item in that array until a match is found._\n\n#### Custom Options\n\nThe optional second argument `options` provides a way to customize how the relative time will be formatted.\n\n##### Units\n\nBy default, the relative time is computed to the best fit unit, but you can explicitly call it to force `units` to be displayed in `\"second\"`, `\"second-short\"`, `\"second-narrow\"`, `\"minute\"`, `\"minute-short\"`, `\"minute-narrow\"`, `\"hour\"`, `\"hour-short\"`, `\"hour-narrow\"`, `\"day\"`, `\"day-short\"`, `\"day-narrow\"`, `\"month\"`, `\"month-short\"`, `\"month-narrow\"`, `\"year\"`, `\"year-short\"` or `\"year-narrow\"`:\n\n```js\nvar rf = new IntlRelativeFormat('en', {\n  units: 'day'\n});\nvar output = rf.format(dateValue);\n```\n\nAs a result, the output will be \"70 days ago\" instead of \"2 months ago\".\n\n##### Style\n\nBy default, the relative time is computed as `\"best fit\"`, which means that instead of \"1 day ago\", it will display \"yesterday\", or \"in 1 year\" will be \"next year\", etc. But you can force to always use the \"numeric\" alternative:\n\n```js\nvar rf = new IntlRelativeFormat('en', {\n  style: 'numeric'\n});\nvar output = rf.format(dateValue);\n```\n\nAs a result, the output will be \"1 day ago\" instead of \"yesterday\".\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 rf = new IntlRelativeFormat('en-us');\nconsole.log(rf.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(date, [options])` Method\n\nThe format method (_which takes a JavaScript date or timestamp_) and optional `options` arguments will compare the `date` with \"now\" (or `options.now`), and returns the formatted string; e.g., \"3 hours ago\" in the corresponding locale passed into the constructor.\n\n```js\nvar output = rf.format(new Date());\nconsole.log(output); // =\u003e \"now\"\n```\n\nIf you wish to specify a \"now\" value, it can be provided via `options.now` and will be used instead of querying `Date.now()` to get the current \"now\" value.\n\n## License\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[npm]: https://www.npmjs.org/package/intl-relativeformat\n[npm-badge]: https://img.shields.io/npm/v/intl-relativeformat.svg?style=flat-square\n[parser]: https://github.com/formatjs/formatjs\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/formatjs/blob/master/LICENSE\n[moment.js]: http://momentjs.com/\n[ecma 402]: http://www.ecma-international.org/ecma-402/1.0/index.html\n[datetimeformat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat\n[numberformat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fformatjs%2Fintl-relativeformat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fformatjs%2Fintl-relativeformat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fformatjs%2Fintl-relativeformat/lists"}