Product
Socket Now Supports uv.lock Files
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
By Trevor Norris - Jan 09, 2025
Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@brightspace-ui/intl
Advanced tools
@brightspace-ui/intl
Internationalization APIs for number, date, time and file size formatting and parsing in D2L Brightspace.
intl
Overview
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.
Installation & Usage
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.
Number Formatting
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:
- minimumFractionDigits: Minimum number of fraction digits to use. Possible values range from
0to20; the default is0. - maximumFractionDigits: Maximum number of fraction digits to use. Possible values range from
0to20; the default is the larger ofminimumFractionDigitsand3. - useGrouping: Whether to use grouping separators, such as thousands separators; the default is
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
Number Parsing
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
Date/Time Formatting
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:
- format: pattern to use when rendering the date-time; default is
'short'.- full: long weekday, month names and timezone. e.g.
'Wednesday, September 23, 2015 1:25 PM EST' - medium: short month names. e.g.
'Sept 23, 2015 1:25 PM' - short: abbreviated date format. e.g.
'9/23/2015 1:25 PM'
- full: long weekday, month names and timezone. e.g.
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:
- format: pattern to use when rendering the date; default is
'short'.- full: long weekday and month names. e.g.
'Wednesday, September 23, 2015' - medium: long month names. e.g.
'September 23, 2015' - short: abbreviated date format. e.g.
'9/23/2015' - monthYear: month and year only. e.g.
'September 2015' - monthDay: month and day only. e.g.
'September 23' - shortMonthDay: short month and day only. e.g.
'Sep 23' - longDayOfWeek: long weekday only. e.g.
'Wednesday' - shortDayOfWeek: short weekday only. e.g.
'Wed' - longMonth: long month only. e.g.
'September' - shortMonth: short month only. e.g.
'Sep'
- full: long weekday and month names. e.g.
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:
- format: pattern to use when rendering the time; default is
'short'.- full: includes timezone. e.g.
'1:25 PM EST' - medium or short: excludes timezone e.g.
'1:25 PM'
- full: includes timezone. e.g.
Date Parsing
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
Time Parsing
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
Date/Time Conversion based on user timezone
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
File Size Formatting
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
List Formatting
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:
- nonBreaking: a Boolean flag, whether to use non-breaking spaces instead of standard spaces; default is
false
Running the test harness
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.
Contributing
Contributions are welcome, please submit a pull request!
Versioning & Releasing
TL;DR: Commits prefixed with
fix:andfeat:will trigger patch and minor releases when merged tomain. Read on for more details...
The semantic-release GitHub Action is called from the release.yml GitHub Action workflow to handle version changes and releasing.
Version Changes
All version changes should obey semantic versioning rules:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
The next version number will be determined from the commit messages since the previous release. Our semantic-release configuration uses the Angular convention when analyzing commits:
- Commits which are prefixed with
fix:orperf:will trigger apatchrelease. Example:fix: validate input before using - Commits which are prefixed with
feat:will trigger aminorrelease. Example:feat: add toggle() method - To trigger a MAJOR release, include
BREAKING CHANGE:with a space or two newlines in the footer of the commit message - Other suggested prefixes which will NOT trigger a release:
build:,ci:,docs:,style:,refactor:andtest:. Example:docs: adding README for new component
To revert a change, add the revert: prefix to the original commit message. This will cause the reverted change to be omitted from the release notes. Example: revert: fix: validate input before using.
Releases
When a release is triggered, it will:
- Update the version in
package.json - Tag the commit
- Create a GitHub release (including release notes)
- Deploy a new package to NPM
Releasing from Maintenance Branches
Occasionally you'll want to backport a feature or bug fix to an older release. semantic-release refers to these as maintenance branches.
Maintenance branch names should be of the form: +([0-9])?(.{+([0-9]),x}).x.
Regular expressions are complicated, but this essentially means branch names should look like:
1.15.xfor patch releases on top of the1.15release (after version1.16exists)2.xfor feature releases on top of the2release (after version3exists)
FAQs
Internationalization APIs for number, date, time and file size formatting and parsing in D2L Brightspace.
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 0 open source maintainers collaborating on the project.
Package last updated on 24 Oct 2023
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.
Related posts
Research
Security News
Gmail For Exfiltration: Malicious npm Packages Target Solana Private Keys and Drain Victims' Wallets
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.
By Kirill Boychenko - Jan 08, 2025
Security News
New Python Packaging Proposal Aims to Solve Phantom Dependency Problem with SBOMs
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
By Sarah Gooding - Jan 07, 2025