# @brightspace-ui/intl 中文文档

规范地址：https://npmcn.com/package/%40brightspace-ui/intl/

版本：3\.48\.5
npm 元数据更新时间：2026-11-02T14:31:14.475Z
中文译文更新时间：2026-11-08T15:23:53.521Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40brightspace-ui/intl
原文对照：https://npmcn.com/package/%40brightspace-ui/intl/?lang=original
项目主页：https://github.com/BrightspaceUI/intl
源码仓库：https://github.com/BrightspaceUI/intl

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：459 kB，88 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2020-01-03T17:13:06.231Z
- 最新版本发布：2026-11-02T14:31:14.262Z
- 近 30 天下载量：42843（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：119（近 12 个月 42 个）

## 中文简介

D2L Brightspace中用于数字,日期,时间和文件大小格式化和解析的国际化API.

## 安装

```sh
npm install @brightspace-ui/intl
```

也可以使用：`pnpm add @brightspace-ui/intl`、`yarn add @brightspace-ui/intl`、`bun add @brightspace-ui/intl`

## README

# 输入

[![NPM version](https://img.shields.io/npm/v/@brightspace-ui/intl.svg)](https://www.npmjs.org/package/@brightspace-ui/intl) [![NPM downloads](https://img.shields.io/npm/dt/@brightspace-ui/intl.svg)](https://www.npmjs.com/package/@brightspace-ui/intl)

## 概览

这个库由用于D2L Brightspace的格式和解析数字,日期,时间和文件大小的API组成. 它还为共同术语提供了本地化.

> 寻找老人 `d2l-intl` 图书馆? 还在这里 [输入 `v2.x` 分支](https://github.com/BrightspaceUI/intl/tree/v2.x)。 。 。 .

不如用标准 [ECMAScript 国际化 API(ECMA-402)](http://www.ecma-international.org/ecma-402/1.0/#sec-8) 财务报告和审定财务报表 [相关的多填充](https://github.com/andyearnshaw/Intl.js)首先,标准不包括任何解析功能。 此外, Blightspace 支持在组织和用户级别上精细的本地化定制—— 配置在本地的 API 中根本不存在 .

## 安装和使用

从国家预防机制安装:

```shell
npm install @brightspace-ui/intl
```

礛 `import` 只有您需要的功能 :

```javascript
import { formatDate, formatTime } from '@brightspace-ui/intl/lib/dateTime.js';
import { formatNumber, formatPercent } from '@brightspace-ui/intl/lib/number.js';
```

所有API将自动通过 `lang` 属性 `<html>` 键。 他们也会寻找各种 `data-` 属性,该属性将存在于Brightspace页面中,用于访问覆盖和时区信息.

## 数字

### 数字格式

整数和十进制数字可以使用 : `formatNumber`。百分比可使用 `formatPercent`选项 `options` 参数表示四舍五入.

```javascript
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
```

选项 :

-   **最小动作数字**: 要使用的最低分数位数。 可能的值范围从 `0` 改为 `20`; 默认为 `0`。 。 。 .
-   **最大行动数字**: 要使用的最大分数位数。 可能的值范围从 `0` 改为 `20`; 默认值大于 `minimumFractionDigits` 财务报告和审定财务报表 `3`。 。 。 .
-   **组合**: 是否使用分组分隔符, 如千分隔符; 默认为 `true`。 。 。 .

格式化为整数( 四舍五入到小数位数 0 ):

```javascript
import { formatNumber } from '@brightspace-ui/intl/lib/number.js';

const value = formatNumber(89.72, {
    maximumFractionDigits: 0
}); // -> '90' in en-US
```

格式化为百分比( 四舍五入为小数位数 2, 但总是显示至少小数位数 2 ):

```javascript
import { formatPercent } from '@brightspace-ui/intl/lib/number.js';

const value = formatPercent(0.333, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
}); // -> '33.30 %' in en-US
```

### 数字分析

这个 `parseNumber` 方法可用于解析在用户用地上所写的整数或小数.

```javascript
import { parseNumber } from '@brightspace-ui/intl/lib/number.js';

const value = parseNumber('-8 942,39'); // -> -8942.39 in fr-CA
```

## 日期和时间

### 日期和时间格式

日期和时间可以在用户的用地中格式化 `formatDate`, (中文(简体) ), `formatTime`, (中文(简体) ), `formatDateTime`,以及 `formatRelativeDateTime`。 。 。 .

时间戳( 自纪元起的毫秒) 可以使用 : `formatDateTimeFromTimestamp`。 。 。 .

合并日期和时间采用格式 `formatDateTime`数字 :

```javascript
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
```

选项 :

-   **格式**: 渲染日期- 时间时使用的模式; 默认为 `'short'`。 。 。 .
    -   **满**:长周日,月名和时区. 譬如说. `'Wednesday, September 23, 2015 1:25 PM EST'`
    -   **介质**:简称. 譬如说. `'Sept 23, 2015 1:25 PM'`
    -   **简称**: 日期格式简略. 譬如说. `'9/23/2015 1:25 PM'`

格式化 a **时间戳** 作为日期和时间:

```javascript
const dateString = formatDateTimeFromTimestamp(
    1607097863123,
    [options]
);
```

选项与 `formatDateTime`;此方法将时间戳转换为 `Date` 在用户中 配置时区,然后返回通过此日期的结果 `formatDateTime`。 。 。 .

格式化 a **时间戳** 仅作为日期:

```javascript
const dateString = formatDateFromTimestamp(
    1607097863123,
    [options]
);
```

选项与 `formatDate`;此方法将时间戳转换为 `Date` 在用户中 配置时区,然后返回通过此日期的结果 `formatDate`。 。 。 .

格式化 a **时间戳** 仅限时间 :

```javascript
const timeString = formatTimeFromTimestamp(
    1607097863123,
    [options]
);
```

选项与 `formatTime`;此方法将时间戳转换为 `Date` 在用户中 配置时区,然后返回通过此日期的结果 `formatTime`。 。 。 .

格式化 a **仅日期** (不含时间部分),使用 `formatDate`数字 :

```javascript
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
```

选项 :

-   **格式**: 渲染日期时使用的模式; 默认为 `'short'`。 。 。 .
    -   **满**:长周日和月名. 譬如说. `'Wednesday, September 23, 2015'`
    -   **介质**:长月名. 譬如说. `'September 23, 2015'`
    -   **简称**: 日期格式简略. 譬如说. `'9/23/2015'`
    -   **年份**:仅以正月为正年. 譬如说. `'September 2015'`
    -   **月份日数**:只限一月一日. 譬如说. `'September 23'`
    -   **短数月日**:仅短一月一日. 譬如说. `'Sep 23'`
    -   **长周日**:只有长的周一. 譬如说. `'Wednesday'`
    -   **简短的周刊**: 工作日短。 譬如说. `'Wed'`
    -   **长月**:仅长一月. 譬如说. `'September'`
    -   **短月数**:仅短一月. 譬如说. `'Sep'`

格式化 a **时间** (不含日期部分),使用 `formatTime`数字 :

```javascript
import { formatTime } from '@brightspace-ui/intl/lib/dateTime.js';

const time = formatTime(
    new Date(2015, 8, 23, 14, 5)
); // -> '오후 14:05' in ko-KR
```

选项 :

-   **格式**: 渲染时间时使用的模式; 默认为 `'short'`。 。 。 .
    -   **满**:包括时区. 譬如说. `'1:25 PM EST'`
    -   **介质** 或者说 **简称**:排除时区,例如:. `'1:25 PM'`

将日期/时间格式化为相对时间,使用 `formatRelativeDateTime`数字 :

```javascript
import { formatRelativeDateTime } from '@brightspace-ui/intl/lib/dateTime.js';

const relativeDateTime = formatRelativeDateTime(
    new Date(2024, 8, 18)
); // If today is 2024-08-22, -> 'last week' in en-US
```

### 日期解析

要解析用户语言中写的日期, 请使用 `parseDate`数字 :

```javascript
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
```

### 时间分析

分析在用户语言中写入的时间, 使用 `parseTime`数字 :

```javascript
import { parseTime } from '@brightspace-ui/intl/lib/dateTime.js';

const date = parseTime('14 h 05'); // in fr-CA
date.getHours(); // -> 14
date.getMinutes(); // -> 5
```

### 基于用户时区的日期/时间转换

将含有 UTC 日期的对象转换为含有对应日期的本地日期的对象 `data-timezone` 属性 :

```javascript
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
```

转换含有一个与 `data-timezone` 属于含有世界协调时日期的对象的属性:

```javascript
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
```

## 文件大小格式化

使用 `formatFileSize` 为用户的语境格式化文件大小.

```javascript
import { formatFileSize } from '@brightspace-ui/intl/lib/fileSize.js';

const fileSize = formatFileSize(100); // -> '100 bytes' in en-US
```

## 列表格式

使用 `getSeparator` 以获取当前区域的适当列表分隔符。 这是一个分隔符,将用在口语中;注意分隔符包含一个空间,适合当地人使用.

```javascript
import { getSeparator } from '@brightspace-ui/intl/lib/list.js';

const separator = getSeparator(); // -> ', ' in en-US
const separator = getSeparator({ nonBreaking: true }); // -> ',\xa0' in en-US
```

选项 :

-   **非断裂**: boolean 旗帜, 是否使用非拆解空格而不是标准空格; 默认为 `false`

## 术语

使用 `getTerminology` 以定义术语值 `d2l.Languages.Terminology.*` 配置变量 .

```javascript
import { getTerminology, TerminologyKey } from '@brightspace-ui/intl/lib/terminology.js';

// Get the terminology value defined by the d2l.Languages.Terminology.Educator config variable
const educatorTerminology = getTerminology(TerminologyKey.Educator);
```

## 语言本地化

这个 `Localize` 类允许在用户首选语言中显示文本.

### 资源

每个资源由一个名称和一个消息组成,必须在 JavaScript 对象中作为密钥值对提供:

```javascript
{ myMessage: "This is my message" }
```

#### 名称

名称应简洁而独到地描述案文的本地化. `camelCase` 建议,尽管 `snake_case` 财务报告和审定财务报表 `kebab-case` 也得到支持.

对于大型项目,资源可按下列方法分类: `:` 字符键。 例如: `parentGroup:subGroup:messageName`。 。 。 .

#### 消息

信息必须符合 [ICU 信件语法](https://formatjs.io/docs/core-concepts/icu-syntax/) 格式。 它支持以下特征: [简单参数](https://formatjs.io/docs/core-concepts/icu-syntax/#simple-argument),则 [`select` 格式](https://formatjs.io/docs/core-concepts/icu-syntax/#select-format) 财务报告和审定财务报表 [复数化](https://formatjs.io/docs/core-concepts/icu-syntax/#plural-format)。 。 。 .

> **说明:** 避免使用ICU消息语法编号,日期和时间格式化功能. 亮空间允许定制这些如何本地化, 因此使用 `formatNumber`, (中文(简体) ), `formatDate` 财务报告和审定财务报表 `formatTime` 换句话说.

### 使用 `Localize`

导入 `Localize` 并创建一个新的实例。 这个 `importFunc` 选项。 它将被传递一个语言标记, 用来获取资源 :

```javascript
import { Localize } from '@brightspace-ui/intl/lib/localize.js';

const localizer = new Localize({
    importFunc: async lang => (await import(`../lang/${lang}.js`)).default
});
```

等待资源到位后再试图使用:

```javascript
await localizer.ready;
```

### `localize()`

这个 `localize()` 方法用于将消息本地化.

如果信件含有参数,请在第二个参数中提供替换值:

```javascript
const helloText = localizer.localize('hello', { firstName: 'Mary' });
```

### `localizeHTML()`

丰富的格式可以包含在信件中,并用 `localizeHTML()` 方法.

#### 基本格式

下列格式化元素被支持在框外:

-   `<p>paragraphs</p>`
-   `line<br></br>breaks` (注意需要端标签)
-   `<b>bold</b>`
-   `<strong>strong</strong>`
-   `<i>italic</i>`
-   `<em>emphasis</em>`

记住 `<strong>` 用于更重要的内容(浏览器用粗体显示此图像),而 `<b>` 仅以视觉方式显示文本,而不增加其重要性.

同样 `<em>` _强调_ 特定文本(浏览器使用斜体显示此图像),而 `<i>` 仅以斜体显示文字,而不强调.

示例

```javascript
{
  myMessage: "This is <b>bold</b> but <em>not</em> all that <strong>important</strong>."
}
```

#### 高级格式

通过提供自定义标签的替换方法,可以实现更先进的格式化,这与参数类似:

```javascript
{
  goHome: "Go <homeLink>home</homeLink>"
}
```

然后导入 `localizeMarkup`数字 :

```javascript
import { localizeMarkup } from '@brightspace-ui/intl/lib/localize.js';
```

,并提供标签替换方法:

```javascript
localizer.localizeHTML('goHome', {
    homeLink: chunks => localizeMarkup`<d2l-link href="/home">${chunks}</d2l-link>`
});
```

除基本格式要素外,这些额外要素也可用于替换方法:

-   `<d2l-link>`
-   `<d2l-tooltip-help>`

### 共同资源

一些本地化资源是常见的,在D2L应用中共享. 为了利用这些资源,设置 `loadCommon` 选项 :

```javascript
import { Localize } from '@brightspace-ui/intl/lib/localize.js';

const localizer = new Localize({
  loadCommon: true
});
```

#### 本地化

以下通用术语的本地化值可以使用 `localizeCommon(name)`数字 :

导航

-   `navigation:back:title` (背书)
-   `navigation:next:title` (下一个)
-   `navigation:previous:title` (先前)

#### 本地化

下列字符的本地化值可以使用 `localizeCharacter(char)`数字 :

-   `'` (隐患)
-   `&` (卫士们)
-   `*` (偷窥)
-   `\` (回击)
-   `:` (结肠)
-   `,` (视频)
-   `>` (比标出相
-   `<` (小于标志)
-   `#` (数字标志)
-   `%` (百分比标志)
-   `|` (管声)
-   `?` (问号)
-   `"` (引号)

```javascript
const value = localizer.localizeCharacter('&'); // -> 'ampersand' in en-US
```

### `onResourcesChange`

提供 `onResourcesChange` 用于在文档语言被更改并有更新资源时执行任务的回调函数:

```javascript
const localizer = new Localize({
    onResourcesChange: () => document.title = localizer.localize('pageTitle')
});
```

要停止监听更改, 请断开实例 :

```javascript
localizer.disconnect()
```

## 发展与促进

复制后, 运行 `npm install` 以安装依赖.

### 运行测试带

开始 a [@ web/ dev- server( 网络服务器)](https://modern-web.dev/docs/dev-server/overview/) 测试带的主机:

```shell
npm start
```

这将允许您在浏览器中测试 intl 库, 并将随任何更改而更新 .

### 捐款

欢迎捐款,请提交拉力请求!

### 版本和发布

此 repo 配置为使用 `semantic-release`输入前缀 `fix:` 财务报告和审定财务报表 `feat:` 合并到 `main`。 。 。 .

为了学习如何从维护分支中产生主要释放和释放,请参见: [语义- 释放 GitHub 动作](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) 文档.

## 常见问题

### @brightspace-ui/intl 是什么？

D2L Brightspace中用于数字,日期,时间和文件大小格式化和解析的国际化API\.

### 如何安装 @brightspace-ui/intl？

在项目目录运行 npm install @brightspace-ui/intl，或使用 pnpm add / yarn add / bun add。

### @brightspace-ui/intl 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/brightspace-ui\_\_intl 是否存在。

### @brightspace-ui/intl 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @brightspace-ui/intl 可以商用吗？

@brightspace-ui/intl 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @brightspace-ui/intl 的下载量有多少？

根据 npm 官方下载统计，@brightspace-ui/intl 在 2026/10/09 – 2026/11/07 这 30 天内被下载 42,843 次，日均约 1,428 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @brightspace-ui/intl 还在维护吗？

最新版本 3\.48\.5 发布于 2026/11/02（6 天前）；至今共发布 119 个版本，其中过去 12 个月发布了 42 个；首次发布于 2020/01/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。