@brightspace-ui/intl
Advanced tools
Readme
This library consists of APIs to format and parse numbers, dates, times and file sizes for use in D2L Brightspace.
Looking for the older
d2l-intllibrary? It's still here in thev2.xbranch.
Why not just use the standard ECMAScript Internationalization API (ECMA-402) and related polyfills? Firstly, the standard doesn't include any parsing functionality. Additionally, Brightspace supports fine-grained locale customization at the organization and user levels -- configuration that simply isn't present in the native APIs.
Install from NPM:
npm install @brightspace-ui/intl
Then import only the functionality you need:
import { formatDate, formatTime } from '@brightspace-ui/intl/lib/dateTime.js';
import { formatNumber, formatPercent } from '@brightspace-ui/intl/lib/number.js';
All of the APIs will automatically detect the document's language via the lang attribute on the <html> element. They'll also look for various data- attributes that will be present in Brightspace pages to access override and timezone information.
Integer and decimal numbers can be formatted in the user's locale using formatNumber. Percentages can be formatted using formatPercent. Use the optional options parameter for rounding.
import { formatNumber, formatPercent } from '@brightspace-ui/intl/lib/number.js';
const number = formatNumber(8902.72, [options]); // -> '8,902.72' in en-US
const percent = formatPercent(0.333, [options]); // -> '33.3 %' in en-US
Options:
0 to 20; the default is 0.0 to 20; the default is the larger of minimumFractionDigits and 3.true.Formatting as an integer (rounded to 0 decimal places):
import { formatNumber } from '@brightspace-ui/intl/lib/number.js';
const value = formatNumber(89.72, {
maximumFractionDigits: 0
}); // -> '90' in en-US
Formatting as a percentage (rounded to 2 decimal places, but always showing at least 2 decimals):
import { formatPercent } from '@brightspace-ui/intl/lib/number.js';
const value = formatPercent(0.333, {
minimumFractionDigits: 2,
maximumFractionDigits: 2
}); // -> '33.30 %' in en-US
The parseNumber method can be used to parse an integer or decimal number written in the user's locale.
import { parseNumber } from '@brightspace-ui/intl/lib/number.js';
const value = parseNumber('-8 942,39'); // -> -8942.39 in fr-CA
Dates and times can be formatted in the user's locale using formatDate, formatTime and formatDateTime.
Timestamps (milliseconds since the epoch) can be formatted in the user's locale and timezone using formatDateTimeFromTimestamp.
Combined dates and times are formatted using formatDateTime:
import { formatDateTime } from '@brightspace-ui/intl/lib/dateTime.js';
const date = formatDateTime(
new Date(2015, 8, 23, 14, 5),
[options]
); // -> '2015-09-23 14:05' in sv-SE
Options:
'short'.
'Wednesday, September 23, 2015 1:25 PM EST''Sept 23, 2015 1:25 PM''9/23/2015 1:25 PM'To format a timestamp as a date and time:
const dateString = formatDateTimeFromTimestamp(
1607097863123,
[options]
);
Options are the same as for formatDateTime; this method converts the timestamp to a Date in the user's
configured time zone, then returns the results of passing this date to formatDateTime.
To format a timestamp as a date only:
const dateString = formatDateFromTimestamp(
1607097863123,
[options]
);
Options are the same as for formatDate; this method converts the timestamp to a Date in the user's
configured time zone, then returns the results of passing this date to formatDate.
To format a timestamp as a time only:
const timeString = formatTimeFromTimestamp(
1607097863123,
[options]
);
Options are the same as for formatTime; this method converts the timestamp to a Date in the user's
configured time zone, then returns the results of passing this date to formatTime.
To format a date only (without the time portion), use formatDate:
import { formatDate } from '@brightspace-ui/intl/lib/dateTime.js';
const value = formatDate(
new Date(2015, 8, 23),
{format: 'full'}
); // -> 'miércoles 23 de septiembre de 2015' in es-MX
Options:
'short'.
'Wednesday, September 23, 2015''September 23, 2015''9/23/2015''September 2015''September 23''Sep 23''Wednesday''Wed''September''Sep'To format a time only (without the date portion), use formatTime:
import { formatTime } from '@brightspace-ui/intl/lib/dateTime.js';
const time = formatTime(
new Date(2015, 8, 23, 14, 5)
); // -> '오후 14:05' in ko-KR
Options:
'short'.
'1:25 PM EST''1:25 PM'To parse a date written in the user's locale, use parseDate:
import { parseDate } from '@brightspace-ui/intl/lib/dateTime.js';
const date = parseDate('2015-09-23'); // in fr-CA
date.getFullYear(); // -> 2015
date.getMonth(); // -> 8 (months are 0-11)
date.getDate(); // -> 23
To parse a time written in the user's locale, use parseTime:
import { parseTime } from '@brightspace-ui/intl/lib/dateTime.js';
const date = parseTime('14 h 05'); // in fr-CA
date.getHours(); // -> 14
date.getMinutes(); // -> 5
To convert an object containing a UTC date to an object containing a local date corresponding to the data-timezone attribute:
import { convertUTCToLocalDateTime } from '@brightspace-ui/intl/lib/dateTime.js';
const UTCDateTime = {
month: 12,
date: 1,
year: 2015,
hours: 8,
minutes: 0,
seconds: 0
};
const localDateTime = convertUTCToLocalDateTime(
UTCDateTime
); // -> { month: 12, date: 1, year: 2015, hours: 3, minutes: 0, seconds: 0 } in America/Toronto
To convert an object containing a local date corresponding to the data-timezone attribute to an object containing a UTC date:
import { convertLocalToUTCDateTime } from '@brightspace-ui/intl/lib/dateTime.js';
const localDateTime = {
month: 12,
date: 1,
year: 2015,
hours: 8,
minutes: 0,
seconds: 0
};
const UTCDateTime = convertLocalToUTCDateTime(
localDateTime
); // -> { month: 12, date: 1, year: 2015, hours: 13, minutes: 0, seconds: 0 } in America/Toronto
Use formatFileSize to format a file size appropriately for the user's locale.
import { formatFileSize } from '@brightspace-ui/intl/lib/fileSize.js';
const fileSize = formatFileSize(100); // -> '100 bytes' in en-US
Use getSeparator to get the appropriate list separator for the current locale. This is a separator that would be used in spoken language; note that the separator includes a space, for locales where it is appropriate.
import { getSeparator } from '@brightspace-ui/intl/lib/list.js';
const separator = getSeparator(); // -> ', ' in en-US
const separator = getSeparator({ nonBreaking: true }); // -> ',\xa0' in en-US
Options:
falseAfter cloning the repo, run npm install to install dependencies.
Start a @web/dev-server that hosts the test harness:
npm start
This will let you test the intl library in a browser, and will update live with any changes.
Contributions are welcome, please submit a pull request!
This repo is configured to use semantic-release. Commits prefixed with fix: and feat: will trigger patch and minor releases when merged to main.
To learn how to create major releases and release from maintenance branches, refer to the semantic-release GitHub Action documentation.
FAQs
Internationalization APIs for number, date, time and file size formatting and parsing in D2L Brightspace.
The npm package @brightspace-ui/intl receives a total of 1,992 weekly downloads. As such, @brightspace-ui/intl popularity was classified as popular.
We found that @brightspace-ui/intl demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.