{"id":15805255,"url":"https://github.com/microsoft/globe","last_synced_at":"2025-07-11T22:06:16.388Z","repository":{"id":37182921,"uuid":"238260376","full_name":"microsoft/globe","owner":"microsoft","description":"Globalization utilities","archived":false,"fork":false,"pushed_at":"2025-04-30T17:42:26.000Z","size":4044,"stargazers_count":29,"open_issues_count":1,"forks_count":12,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-27T00:32:32.778Z","etag":null,"topics":["g11n","globalization","globe","i18n","internalization","microsoft"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":"change/@microsoft-globe-8275cb61-311f-41ad-9d90-a837ad94760a.json","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-04T17:09:37.000Z","updated_at":"2025-04-04T02:02:10.000Z","dependencies_parsed_at":"2024-10-03T17:23:40.768Z","dependency_job_id":"26c8a141-b057-433d-a726-3ac1b2289eae","html_url":"https://github.com/microsoft/globe","commit_stats":{"total_commits":103,"total_committers":13,"mean_commits":7.923076923076923,"dds":0.6019417475728155,"last_synced_commit":"5f89d94c2a9a6892ae64748fd408cbb7ffed859e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/microsoft/globe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fglobe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fglobe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fglobe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fglobe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/globe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fglobe/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263239730,"owners_count":23435686,"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":["g11n","globalization","globe","i18n","internalization","microsoft"],"created_at":"2024-10-05T02:05:37.493Z","updated_at":"2025-07-11T22:06:16.364Z","avatar_url":"https://github.com/microsoft.png","language":"TypeScript","readme":"# Globe\n\nProvides localization services for Electron and the browser.\nRespects the OS date and time format configuration.\n\n## Installation\n\n`npm i`[`@microsoft/globe`](https://www.npmjs.com/package/@microsoft/globe)\n\n## Usage\n\n```typescript\nimport { TimeStringFormat, DateTimeFormatOptions, DateTimeFormatter } from 'globe';\n\n// Instantiate the formatter\nconst dateTimeFormatter = new DateTimeFormatter(locale: string | ILocaleInfo);\n```\n\n`locale` is either a locale string (e.g.: `en-US`) or `ILocaleInfo` instance:\n\n```typescript\ntype ILocaleInfo = {\n  // Supported platform\n  platform: 'windows' | 'macos';\n\n  // OS date \u0026 time format settings (see below for OS support)\n  regionalFormat: string; // e.g.: 'en-US'\n  shortDate: string; // e.g.: 'dd/MM/y'\n  longDate: string; // e.g.: 'd MMMM y'\n  fullDate: string; // e.g.: 'EEEE d MMMM y'\n  shortTime: string; // e.g.: 'HH:mm'\n};\n```\n\nTo format a date and time value:\n\n```typescript\n/**\n * Localize the date/time\n * @param date The date/time to localize\n * @param format The format to be used for the localization\n * @returns The localized date/time string\n */\nfunction formatDateTime(date: number | Date, format: DateTimeFormatOptions) {\n  return dateTimeFormatter.formatDateTime(date, format);\n}\n```\n\n**The function throws** in case an unexpected OS date and time format string is\nprovided! Most likely this will happen if you feed it the OS strings verbatim and\nthe OS is configured with a custom date/time format string. If you don't desire\nthis behavior, you can choose your own fallback (and telemetry) by wrapping the\ncall to Globe and redoing it without OS-honoring support in case it fails with\nthe *Unexpected format string* error.\n\n### OS Support\n\nGlobe is able to honor OS system date and time formatting settings, but it does\nnot do OS detection and date and time settings querying out of the box as these\nfeatures depend on the context you're using Globe in.\n\nIf you want to take an advantage of this feature, we recommend you follow this\npattern:\n\n- Make `window.getLocaleInfoAsync` available (return `Promise\u003cILocaleInfo\u003e`)\n- Cache the result of that function and provide it in the `DateTimeFormatter`\n  constructor\n- Use the exported `getLocaleInfoAsync` alias function if you prefer, which\n  wraps the `window.getLocaleInfoAsync` function for you:\n\n```typescript\nimport { getLocaleInfoAsync } from '@microsoft/globe';\n// Provide the supported platform name and obtain the OS locale settings\nconst localeInfo = await getLocaleInfoAsync(/* 'windows` | 'macos' */);\nnew DateTimeFormatter(localeInfo);\n```\n\n#### Windows\n\nThe values provided can be found in Date \u0026 Time this way:\n\n- Click on the date and time in the taskbar\n- Click on Adjust date and time\n- Click on Region \u0026 language (here you see the values formatted)\n- Click on Advanced\n- Check the values of short date, long date and short time\n\n![](./windows.png)\n\n#### macOS\n\n- Click on the date and time in the menubar\n- Click on Open date and time preferences\n- Click on Date and time\n- Click on Oppen language and region\n- Click on Advanced\n- Click on Dates\n- Check the values of short and long\n\n![](./macos-dates.png)\n\n- Click on Times\n- Check the value of\n\n![](./macos-times.png)\n\n[MacOS format patterns reference](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/Articles/dfDateFormatting10_4.html#//apple_ref/doc/uid/TP40002369-SW1)\n\n## Building\n\n```sh\nnpm install\nnpm run build\n```\n\n## Testing\n\nBuild the package first: `npm run build`.\n\n`npm test`\n\nThere is a [GitHub Actions workflow](.github/workflows/main.yml) which runs the\ntests on every push to any branch.\n\n## GitHub Release Publishing\n\nGitHub Releases are made manually by @TomasHubelbauer at the moment.\n\n## NPM Release Publishing\n\nDon't forget to build prior to cutting a release!\n\n```sh\n# --tag=next pro pre-release (also include a pre-release tag in the version code)\nnpm publish [--tag=next]\n# @microsoft/globe\n```\n\nInstall the pre-release package using: `npm i @microsoft/globe@next`\n\nNPM Releases are made manually by @TomasHubelbauer at the moment.\n\n## Release Notes\n\n### `4.1.4` 2024-02-14\nAdd new format `MEDIUM_DATE_SHORT_TIME`\n\n### `4.1.3` 2021-08-09\nAttempting to fix VDI issues on Electron\n### `4.1.2` 2021-03-31\nFixed 12 hours format for Windows\n\n### `4.1.1` 2021-02-18\nUse for loops in an attempt to reduce memory consumption\n\n### `4.1.0` 2021-02-03\nUse reducers in an attempt to reduce memory consumption (eliminate anonymous functions)\nBetter checks for cases where time zone is not provided by default\n\n### `4.0.0` 2020-11-10\nUse `hourCycle` for mac as it is supported in Electron 8\n\n### `3.5.0` 2020-10-29\nMac full date format\n\n### `3.4.0` 2020-10-29\nSupport quotes in format\nSupport K and k tokens for mac\n\n### `3.3.0` 2020-10-057\nRemoved `SHORT_DATE_TIME_NO_YEAR`\n\n### `3.2.0` 2020-10-05\nAdd new format `SHORT_DATE_TIME_NO_YEAR`\n\n### `3.1.0` 2020-09-08\nAdd getLocaleInfoAsync to module export\n\n### `3.0.1` 2020-09-04\nImprove error logging for unknown formats\n\n### `3.0.0` 2020-07-22\nAvoid depending on Intl.DateTimeFormatParts which is not available in es5\n\n### `2.8.1` 2020-07-20\nSafeDateTimeFormat with fallback to UTC if timezone is not detected or provided\nUse 0 instead of 24 for H and HH tokens\n\n### `2.8.0` 2020-06-29\n\nPrecompute formats so that applying is faster.\nAdded FULL, FULL_WITH_YEAR, FULL_TIME, LONG_TIME_WITH_TIMEZONE, LONG_WITH_TIMEZONE, LONG_WITH_YEAR_TIMEZONE, SHORT and SHORT_WITH_YEAR formats.\n\n### `2.7.4` 2020-06-29\n\nDo not use `for...of` because of perf impact.\n\n### `2.7.3` 2020-06-16\n\nImproved performance, by adding more caching.\n\n### `2.7.2` 2020-05-25\n\nFixed a bug in Windows AM/PM token detection in the OS formatting string.\nInstead for looking for either `t` or `tt`, Globe was only looking for `tt`.\n\n### `2.7.1` 2020-05-19\n\nFixed typo in seconds in long date and time format.\n\n### `2.7.0` 2020-05-19\n\nAdded formatting rules for:\n\n- Long date and time\n- Long weekday and long time\n- Long weekday and short time\n- Short weekday and long time\n- Short weekday and short time\n\n### `2.6.2` 2020-05-14\n\nFixed an issue where Windows OS format string was treated as if it was a\nmacOS format string.\n\n### `2.6.1` 2020-05-14\n\nWe've added preliminary handling for AM/PM (day period) format which\nsupports the `HOUR_ONLY` option when using the OS date and time format strings.\nThe supported OSs (macOS and Windows) do not expose a dedicated format string\nfor an hour-only scenario, so we detect whether the OS format string for\nshort date includes the AM/PM format string token and constuct a makeshift\n`HOUR_ONLY` format string for that case which either also includes AM/PM or\ndoesn't depending on if the original short time format string did.\n\n### `2.6.0` 2020-05-04\n\nWe've switched to a single-level cache between the pair made up by the locale\nand the format options stringified and the DateTimeFormat Intl instance.\n\nPreviously the cache was two-level, a map for the locale (string) and a weak\nmap for the format options (object), which had the same performance, but was\nmore complex and needlessly so, because JSON.stringify is so fast being native\ncode, the overhead has actually decreased when using it for the cache key.\n\nThe access pattern of Globe is now such that the first call to `formatDate`\ngiven an format options object (or `undefined`) takes about 20ms, which is\nthe cost of initializing and caching the Intl.DateTimeFormat instance and\nsubsequent calls are practically equivalent in speed to raw Intl, meaning\nthey take \u003c1ms.\n\n### `2.5.0` 2020-05-04\n\nAdd missing key coercion which caused the locale+format cache to have no effect\nin case no format was provided.\n\n### `2.4.0` 2020-05-04\n\nCaching internal `Intl.DateTimeFormat` instances keyed by the given locale and\nformat object.\n\n### `2.3.0` 2020-03-09\n\nAdded HOUR_ONLY pattern.\n\n### `2.2.0` 2020-03-05\n\nAdded few more date time formatting patterns, like Medium and Full dates and times.\n\n### `2.1.0` 2020-02-24\n\nRefactored the `DateTimeFormatter` constructor to accept either a locale\nstring or an instance of `ILocaleInfo` and added information and support\nfor obtaining `ILocaleInfo` through OS settings.\n\n### `1.0.2` 2020-02-11\n\nRelease a version with the release notes in the readme.\n\n### `1.0.1` 2020-02-11\n\n- Fixed a typo in the file name in the `module` field of `package.json`\n- Fixed installation instructions to use the current scope - `@microsoft`\n- Fixed the usage sample and clean up the readme a bit\n\n### `1.0.0` 2020-02-06\n\nInitial release of the code pulled out of a larger codebase for\npublic consumption.\n\n## To-Do\n\n### Set up Jest to run with TypeScript and TSDX and in watch mode\n\nRight now the tests are too rudimentary and are in JavaScript. Doing this will make it\neasier, faster and less error-prone to test the library.\n\n### Set up automated GitHub and NPM releases\n\nWe don't cut releases too often, but this will still be useful to make the release\nprocess reproducible, reliable and consistent.\n\n### Add more docs, especially around formatting based on OS date time settings\n\nWe're in a process of redesigning the OS-formatting portion of this library and will\npublish a design documentation first and an implementation PR second when we're ready\nto invest more resources into improving this.\n\n### Throw a custom error when hitting an unexpected OS date and time format string\n\nThis will be useful when attempting to catch this exact error. Right now we only throw\nthis error so barring programming errors any error that can possibly be caught is this\none, but it will be better to provide prototype equality (`e instanceof OSDateTimeError`)\nto be able to catch more selectively and confidently.\n\n## Contributing\n\nContributions are welcome (see the [CONTRIBUTING](./CONTRIBUTING.md) file),\nthough please keep in mind the work-in-progress proof-of-concept state.\nMight make sense to just observe/discuss until the thing gets stable and well-documented.\n\n## License\n\nThis project is licensed under the MIT License, see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fglobe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fglobe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fglobe/lists"}