Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mathieuprog/user-locale
https://github.com/mathieuprog/user-locale
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/mathieuprog/user-locale
- Owner: mathieuprog
- License: apache-2.0
- Created: 2022-11-14T13:42:14.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-24T06:15:52.000Z (5 months ago)
- Last Synced: 2024-09-24T08:35:59.464Z (4 months ago)
- Language: TypeScript
- Size: 113 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# user-locale
`user-locale` provides functions to retrieve default locale parameters from the user's browser and system.
The functions allow to retrieve:
* the date format;
* the time format;
* the number format;
* the preferred language tags (en-US, en, …);
* the time zone;
* the guessed country (from the time zone and preferred language tags);
* the first day of the week (from the guessed country);
* the color scheme (as configured in the OS or user agent).## Usage
### Date format
`getDateFormat()` returns the order of the date components and the separator of the components.
```typescript
import { DateEndianness, DateFormat, getDateFormat } from 'user-locale';getDateFormat()
```A return value looks like:
```typescript
const dateFormat: DateFormat = {
endianness: DateEndianness.LittleEndian,
separator: '/'
}
```The `endianness` property allows to know in what order the date components are placed:
- `DateEndianness.BigEndian`: year, month, day
- `DateEndianness.LittleEndian`: day, month, year
- `DateEndianness.MiddleEndian`: month, day, year### Time format
`getTimeFormat()` returns whether the clock is the 12-hour clock or 24-hour clock, and the separator of the time components.
```typescript
import { getTimeFormat, TimeFormat } from 'user-locale';getTimeFormat()
```A return value looks like:
```typescript
const timeFormat: TimeFormat = {
is24HourClock: true,
separator: ':'
}
```### Number format
`getNumberFormat()` returns a value from the NumberFormat enum, which indicates the characters of the thousands grouping and the decimal separator.
```typescript
import { getNumberFormat, NumberFormat } from 'user-locale';getNumberFormat()
```The possible returned values are:
```typescript
NumberFormat.CommaPeriod // e.g. for locale 'en-US'
NumberFormat.PeriodComma // e.g. for locale 'de-DE'
NumberFormat.SpaceComma // e.g. for locale 'fr-FR'
```### Preferred language tags
`getPreferredLanguageTags` returns the preferred (BCP 47) language tags.
```typescript
import { getPreferredLanguageTags } from 'user-locale';getPreferredLanguageTags() // ['en-US', 'en']
````user-locale` includes a convenient utility function, `getNativeLanguageNames()`, which returns an array of objects containing language names and their corresponding tags. Each language name is written in its native language.
```typescript
import { getNativeLanguageNames } from 'user-locale';getNativeLanguageNames()
```You can optionally provide a list of specific language tags to filter the results:
```typescript
import { getNativeLanguageNames } from 'user-locale';getNativeLanguageNames('fr', 'en') // [{ "tag": "en", "name": "English" }, { "tag": "fr", "name": "Français" }]
```### Time zone
`getTimeZone` returns the time zone.
```typescript
import { getTimeZone } from 'user-locale';getTimeZone() // 'Asia/Bangkok'
```### Country
`guessCountryCode` guesses the country from the time zone and preferred language tags.
```typescript
import { guessCountryCode } from 'user-locale';guessCountryCode() // ['KH', 'LA', 'TH', 'VN']
```The function returns an array of possible countries.
It first gets the list of countries which use the user's time zone (for instance, "Asia/Bangkok" is used in Thailand, Vietnam, Laos and Cambodia),
then filters out this list by any country code present in the preferred language tags (for instance, `['th', 'th-TH']` includes the country code of Thailand).If the function returns only one element, it is fairly likely that the identified country is correct.
### First day of the week
`getFirstDayOfWeek` returns the first day of the week, based on the country that has been guessed.
```typescript
import { FirstDayOfWeek, getFirstDayOfWeek } from 'user-locale';getFirstDayOfWeek() // FirstDayOfWeek.Monday
```### Color scheme
`getColorScheme` returns the color scheme as configured in the OS or user agent.
```typescript
import { ColorScheme, getColorScheme } from 'user-locale';getColorScheme() // ColorScheme.Dark
```### Utility functions
```typescript
import { dateFormatter, dateTimeFormatter, timeFormatter, numberFormatter } from 'user-locale';numberFormatter(NumberFormat.PeriodComma)(1000.01) // '1.000,01'
dateFormatter({ endianness: DateEndianness.LittleEndian, separator: '/' })(Temporal.PlainDate.from('2023-09-02')) // '02/09/2023'
timeFormatter({ is24HourClock: true, separator: ':' }, { precision: 'minute' })(Temporal.PlainTime.from('13:30:05')) // '13:30'
const formatDate = dateFormatter({ endianness: DateEndianness.LittleEndian, separator: '/' })
const formatTime = timeFormatter({ is24HourClock: false, separator: ':' }, { precision: 'second', omitZeroUnits: true })
dateTimeFormatter(formatDate, formatTime)(Temporal.PlainDateTime.from('2023-09-02 00:00:00')) // '02/09/2023 12 AM'
```## Install
You can get `user-locale` via [npm](http://npmjs.com).
```
npm install user-locale
```