# @americana/diplomat 中文文档

规范地址：https://npmcn.com/package/%40americana/diplomat/

版本：0\.6\.0
npm 元数据更新时间：2026-08-04T02:07:58.682Z
中文译文更新时间：2026-11-06T09:19:02.723Z
软件包许可：CC0-1\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40americana/diplomat
原文对照：https://npmcn.com/package/%40americana/diplomat/?lang=original
项目主页：https://github.com/osm-americana/maplibre-gl-diplomat#readme
源码仓库：https://github.com/osm-americana/maplibre-gl-diplomat

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

- 包体积（解压后）：1000 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：maplibre-gl ^5\.22\.0 \|\| ^6\.0\.0
- 首次发布：2025-11-27T00:28:42.723Z
- 最新版本发布：2026-08-04T02:07:58.483Z
- 近 30 天下载量：3624（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

MapLibre GL JS 的国际化插件

## 安装

```sh
npm install @americana/diplomat
```

也可以使用：`pnpm add @americana/diplomat`、`yarn add @americana/diplomat`、`bun add @americana/diplomat`

## README

# 外交官

外交官为国际观众准备了互动地图。 有几行代码,你的 [MapLibre GL 联合来文](https://github.com/maplibre/maplibre-gl-js/)– 有动力的地图会讲用户喜欢的语言,同时让他们了解世界各地的当地语言.

| 在此之前 | 之后 |
| --- | --- |
| ![Navajo Nation;Naabeehó Bináhásdzo](https://npmcn.com/package/%40americana/diplomat/docs/navajo-nation.png) | [![Nación Navajo (Navajo Nation • Naabeehó Bináhásdzo)](https://npmcn.com/package/%40americana/diplomat/docs/navajo-nation-es.png)](https://americanamap.org/#map=9/36.2134/-109.2837&language=es) |
| ![North Sea / Nordsee / Noordzee / Nordsøen / Nordsjøen / Mer du Nord](https://npmcn.com/package/%40americana/diplomat/docs/north-sea.png) | [![Mare Germanicum](https://npmcn.com/package/%40americana/diplomat/docs/north-sea-la.png)](https://americanamap.org/#map=4/56/3&language=la) |
| ![Ross Avenue;Tennessee Avenue at Rhode Island Avenue;Section Avenue](https://npmcn.com/package/%40americana/diplomat/docs/section-ross.png) | [![Ross Avenue • Tennessee Avenue at Rhode Island Avenue • Section Avenue](https://npmcn.com/package/%40americana/diplomat/docs/section-ross-en.png)](https://americanamap.org/#map=17/39.168568/-84.460075) |

## 特征

外交官给予各方双赢:

-   适合用户首选语言的标签.
-   尊重多语制,可选的双重语言标签:既包括用户首选的语言,也包括当地本地语言.
-   识别框外的任何语言、方言或脚本,并配有复杂的语言代码.

外交官让设计师保存相貌:

-   高效使用多线和内线标签布局的空间.
-   在标签中复制名称以避免杂乱.
-   适当时保留英语外来语地名中的二甲词.
-   尊重从右到左和垂直的文字布局.

外交官在幕后悄悄工作:

-   在运行时更改苍蝇上的样式 – 不需要为每种语言发布新的样式或平板.
-   您选择要本地化的样式层, 或者自动本地化 .
-   支持多种流行的矢量平板图而无需黑客工作,外加自定义的矢量平板和GeoJSON源.

所有本地化都取决于地图数据源中是否有本地化名称. 见 [说明](https://npmcn.com/package/%40americana/diplomat/#readme-caveats) 更多细节.

## 所需资源

外交官与使用MapLibre GL JS v5.22.0及以上的应用程序相兼容.

样式表必须使用更新的 [表达式](https://maplibre.org/maplibre-style-spec/expressions/) 语法; [遗留样式函数](https://maplibre.org/maplibre-style-spec/deprecations/#function) 不支持。 样式表的来源必须符合 [外交官的计划](https://npmcn.com/package/%40americana/diplomat/#readme-schema)。一些流行的矢量瓦已经符合这一计划,包括:

-   [打开地图](https://openmaptiles.org/schema/) 执行,例如, [映射轮胎](https://cloud.maptiler.com/tiles/v3-openmaptiles/), (中文(简体) ), [打开自由映射](https://openfreemap.org/), (中文(简体) ), [OpenStreetMap 美国.](https://tiles.openstreetmap.us/vector/openmaptiles/), (中文(简体) ), [斯塔迪亚地图](https://docs.stadiamaps.com/vector/)
-   [拼图](https://tilezen.readthedocs.io/en/latest/layers/) 执行,例如, [蛋白质](https://protomaps.com/)

附加配置后,外交官会支持更多的向量牌,包括:

-   [地图箱街道](https://docs.mapbox.com/data/tilesets/reference/mapbox-streets-v8/#names)
-   [地图工具kit](https://docs.maptoolkit.com/vector-tiles/schema-reference/#standard-fields)
-   [打开历史地图](https://wiki.openstreetmap.org/wiki/OpenHistoricalMap/Reuse#Vector_tiles)
-   [短面包](https://shortbread-tiles.org/schema/) 执行,例如, [OpenStreetMap.org (英语)](https://vector.openstreetmap.org/), (中文(简体) ), [佛萨提斯](https://github.com/versatiles-org/versatiles-generator/)

## 安装

此插件可用为 [国家防范机制一揽子计划](https://www.npmjs.com/package/@americana/diplomat)。要安装它,请运行以下命令:

```sh
npm install @americana/diplomat
```

也可以将插件作为独立的脚本从 CDN 中包含,例如 [(单位:公斤)](https://unpkg.com/@americana/diplomat/index.js)。 。 。 .

## 使用量

导入外交官为模块 :

```js
import * as Diplomat from "@americana/diplomat";
```

在创建实例后 `maplibregl.Map`,为 `styledata` 将地图本地化的事件 :

```js
map.once("styledata", (event) => {
  Diplomat.localizeStyle(map);
});
```

如果您的样式表使用不同格式的名称密钥的平板, 如 OpenHistoricalMap 或 Shortbread , 请在将图层本地化时设置格式, 例如 :

```js
map.once("styledata", (event) => {
  let locales = Diplomat.getLocales();
  Diplomat.localizeStyle(map, locales, {
    localizedNamePropertyFormat: "name_$1",
  });
});
```

如果你设定 `hash` 选项到创建时的字符串 `Map`您可以让这个代码响应 `language` uRL散列中的参数。 每当散列改变时, 添加窗口事件倾听器, 以更新层 :

```js
addEventListener("hashchange", (event) => {
  let oldLanguage = Diplomat.getLanguageFromURL(new URL(event.oldURL));
  let newLanguage = Diplomat.getLanguageFromURL(new URL(event.newURL));

  if (oldLanguage !== newLanguage) {
    Diplomat.localizeStyle(map);
  }
});
```

同样,您可以立即对用户对其浏览器语言偏好所做的任何实时修改作出反应:

```js
addEventListener("languagechange", (event) => {
  Diplomat.localizeStyle(map);
});
```

> \[注\] 默认情况下,MapLibre GL JS不支持双向文本. 阿拉伯语、希伯来语和其他从右到左的语言,除非你 [安装映射盒- gl- ttl- text 插件](https://maplibre.org/maplibre-gl-js/docs/examples/add-support-for-right-to-left-scripts/)。 。 。 .

## 司马

外交官可以操纵任意GeoJSON或向量瓦源,只要它在每个特性上包含以下属性: 1

-   **`name`** (单位:千美元)`string`:以当地或官方语言取名. 您可以通过设置 `unlocalizedNameProperty` 选项 [`maplibregl.Map.prototype.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibreglmapprototypelocalizestyle)。 。 。 .
-   **`name:xyz`** (单位:千美元)`string`: 另一种语言中的名称, 其中 日记 是一个有效的 [IETF 语言标记](https://en.wikipedia.org/wiki/IETF_language_tag)。例如, `name:zh` 对于中文, `name:zh-Hant` 传统汉语, `name:zh-Hant-TW` 用于传统中文(台湾),以及 `name:zh-Latn-pinyin` 中文的皮宁语 您可以通过设置 `localizedNamePropertyFormat` 选项 [`maplibregl.Map.prototype.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibreglmapprototypelocalizestyle)。 。 。 .

用于兼容 [打开地图](https://openmaptiles.org/schema/) 计划, `name_en` 财务报告和审定财务报表 `name_de` 被确认为替代 `name:en` 财务报告和审定财务报表 `name:de` 分别用于英文和德文,但仅限于 `transportation_name` 层。 出于性能原因,外交官不默认为任何其他语言或层次寻找这种格式.

每个被支持的属性可被设定为一个数值列表,由 [分号](https://wiki.openstreetmap.org/wiki/Semi-colon_value_separator)例如,如果一个地方同时讲英语和法语, `name` 应该是 `English Name;French Name`同样,如果一个地标在西班牙语中有三个同样通用的名称,无论方言如何, `name:es` 应该是 `Nombre Uno;Nombre Dos;Nombre Tres`。列表可以包含无限数量的值。 在罕见的单名包含分号的情况下,它应该作为双分号被逃脱(`;;`) (中文(简体) ).

原始的基础数据源(如OpenStreetMap)只要GeoJSON或矢量瓦片源将其翻译为这个计划,可能遵循不同的一套常规.

## API 密码

此插件将多个符号添加到 a `maplibregl.Diplomat` 命名空间,并在每个实例中添加一个单一方法 `maplibregl.Map`。以下文档使用标记 `maplibregl.Diplomat.*` 如果你把外交官列为剧本的话 但是,如果您将外交官导入为模块,这些符号会被直接导入到您的代码中,而没有任何命名间隔.

### `maplibregl.Diplomat.localizedName`

在用户首选语言中生成名称的表达式,每个表达式在单独的一行上.

如果您正在程序化构建整个样式表, 请使用此常数 `maplibregl.Map` 并想要对哪几层的标签布局有比 [`maplibregl.Map.prototype.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibreglmapprototypelocalizestyle) 提供.

这种表达方式适用于贴出一种特征的标签,这种特征几乎总是有用户首选语言中熟悉的译名,如国名. 对于一些小的地物,例如感兴趣的地点,也是合适的,因为额外的当地语言光泽会把地图弄乱.

示例

```js
map.setLayoutProperty(
  "country-labels",
  "text-field",
  maplibregl.Diplomat.localizedName,
);
```

### `maplibregl.Diplomat.localizedNameInline`

一个在用户首选语言中生成名字的表达式,都在同一行上.

如果您正在程序化构建整个样式表, 请使用此常数 `maplibregl.Map` 并想要对哪几层的标签布局有比 [`maplibregl.Map.prototype.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibreglmapprototypelocalizestyle) 提供.

这种表达式适合给一个线性特征贴上标签,例如公路或水道. 符号层 [`symbol-placement`](https://maplibre.org/maplibre-style-spec/layers/#symbol-placement) 布局属性应设置为任一 `line` 或者说 `line-center`。 。 。 .

示例

```js
map.setLayoutProperty(
  "road-labels",
  "text-field",
  maplibregl.Diplomat.localizedNameInline,
);
```

### `maplibre.Diplomat.localizedNameWithLocalGloss`

一种在用户首选语言中生成名称的表达式,如果其不同,则在括号中以本地语言生成名称.

如果您正在程序化构建整个样式表, 请使用此常数 `maplibregl.Map` 并想要对哪几层的标签布局有比 [`maplibregl.Map.prototype.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibreglmapprototypelocalizestyle) 提供.

这种表达方式适合给一种特性贴上标签,这种特性有时只被翻译成用户偏好的语言,例如城市或城镇的名称. 额外的本地语言拼写尊重当地风俗并随时告知用户,但也可能有风险 [信息超载](https://en.wikipedia.org/wiki/Information_overload) 并挤出其他有用的标签.

示例

```js
map.setLayoutProperty(
  "city-labels",
  "text-field",
  maplibregl.Diplomat.localizedNameWithLocalGloss,
);
```

### `maplibregl.Diplomat.getLocalizedCountryNameExpression()`

返回一个表达式,将给定的国家代码转换成用户首选语言中的人可读名称.

这种方法对于OpenMapTiles所提供动力的样式表是有用的,它只在边界两侧提供国家ISO 3166-1 alpha-3代码,而不会在任何语言中提供国家全名.

参数:

-   **`code`** (单位:千美元)`string`:一种对ISO 3166-1α-3国家代码进行评价的表达式.

示例

```js
map.setLayoutProperty(
  "boundary-edge-labels",
  "text-field",
  maplibregl.Diplomat.getLocalizedCountryNameExpression(["get", "adm0_l"]),
);
```

> \[注\] 使用 [`maplibregl.Diplomat.getGlobalStateForLocalization()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibregldiplomatgetglobalstateforlocalization) ,然后调用 [`maplibregl.Map.prototype.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibreglmapprototypelocalizestyle)。否则,该表达式将评价为原始国家代码.

### `maplibregl.Diplomat.getGlobalStateForLocalization()`

返回外交官需要完全本地化样式的全球状态 .

如果您正在按程序构建样式表, 您可以使用这种方法来填充一个 `state` 样式表根的属性在初始化 a `maplibregl.Map`。您除了来自此对象的属性之外,还可以添加额外的全局性属性,只要您避免对对象进行深克隆.

如果您的样式表由 OpenMapTiles 提供动力, 您需要设置这个全局状态对象, 以便定位来自此的边框标签 [`boundary`](https://openmaptiles.org/schema/#boundary) 层。 否则,用户将只看到ISO 3166-1α-3代码,因为OpenMapTiles只提供这些代码,而不是边界两侧的完整国名.

参数:

-   **`locales`** (单位:千美元)`string`:用于格式化国名的地块.
-   **`options.uppercaseCountryNames`** (单位:千美元)`boolean`:是否在所有大写中写出国名,尊重当地人的案例惯例. 如果您打算在大写中显示边框标签, 请启用此选项, 因为 `upcase` 表达式运算符是局部不敏感.

示例

```js
map.once("styledata", (event) => {
  let localizationState = maplibregl.Diplomat.getGlobalStateForLocalization(
    getLocales(),
    {
      uppercaseCountryNames: true,
    },
  );
  for (let [key, value] of Object.entries(localizationState)) {
    map.setGlobalStateProperty(key, value);
  }
});
```

### `maplibregl.Diplomat.getLocales()`

返回用户喜欢的语言.

示例

```js
maplibregl.Diplomat.getLocales().includes("en");
```

### `maplibregl.Diplomat.getRelatedLanguageTags()`

返回与给定语言标记相关的语言标记数组,从最具体到最不具体排序.

参数:

-   **`tag`** (单位:千美元)`string`: 返回语言标记相关的语言标记.

返回已排序的相关语言标记数组,或空数组,如果 `tag` 是错的.

示例

```js
maplibregl.Diplomat.getRelatedLanguageTags("sr-RS").includes("sr-Cyrl");
maplibregl.Diplomat.getRelatedLanguageTags("zh").includes("zh-Hans-CN");
```

### `maplibregl.Diplomat.getResolvedLocaleExpression()`

回返a `case` 表达式,该表达式将评价语言 [`localizedName`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibrediplomatlocalizedname), (中文(简体) ), [`localizedNameInline`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibrediplomatlocalizednameinline),以及 [`localizedNameWithLocalGloss`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibrediplomatlocalizednamewithlocalgloss) 下定决心 用于设置除此之外的其他布局属性 `text-field`,例如 `text-font` 财务报告和审定财务报表 `text-size`。 。 。 .

参数:

-   **`locales`** (单位:千美元)`string[]`:要包含的名称字段的地块.
-   **`options.includesLegacyFields`** (单位:千美元)`boolean`:是否包含包含下划线的更老字段,对于没有向结肠语法过渡的地层.
-   **`options.unlocalizedNameProperty`** (单位:千美元)`string`: 持有无地名的财产名称.
-   **`options.localizedNamePropertyFormat`** (单位:千美元)`string`: 本地化名称的属性格式,其中 `$1` 替换为 IETF 语言标记.

示例

```js
maplibregl.Diplomat.getResolvedLocaleExpression(
  maplibregl.Diplomat.getLocales(),
);
```

### `maplibregl.Diplomat.localizeStyle()`

更新每个样式层 `text-field` 值以匹配给定的地盘,沿途升级任何无法定位的地层.

如果没有 `options.layers` 也没有 `options.sourceLayers` 以 `options`,该函数使任何样式层都能够本地化,从而获得在 `options.unlocalizedNameProperty`,或 `name` 默认.

参数:

-   **`map`** (单位:千美元)`maplibregl.Map`: 本地化地图.
-   **`locales`** (单位:千美元)`[string]`: 插入到每层的区域, 作为逗号分隔列表 [IETF 语言标记](https://en.wikipedia.org/wiki/IETF_language_tag)使用 `language` URL散列参数或浏览器默认偏好.
-   **`options`** (单位:千美元)`object`:
    -   **`layers`** (单位:千美元)`[string]`:带有这些ID的样式层会变得可本地化.
    -   **`sourceLayers`** (单位:千美元)`[string]`:使用这些源地层的样式层会变得可本地化. 这些是源层ID,而不是样式层ID.
    -   **`unlocalizedNameProperty`** (单位:千美元)`string`: 持有无地名的财产名称. `name` 默认.
    -   **`localizedNamePropertyFormat`** (单位:千美元)`string`: 本地化名称的属性格式,其中 `$1` 替换为 IETF 语言标记. `name:$1` 默认.
    -   **`glossLocalNames`** (单位:千美元)`boolean`:是否将每个标签格式化为一个双重语言的标签,包括一个本地名光泽.
    -   **`uppercaseCountryNames`** (单位:千美元)`boolean`:是否在所有大写中写出国名,尊重当地人的案例惯例.

示例

```js
maplibregl.Diplomat.localizeStyle(map, ["eo"], {
  sourceLayers: ["place"],
  glossLocalNames: true,
});
```

### `maplibregl.Map.prototype.localizeStyle()`

一个包装 [`maplibregl.Diplomat.localizeStyle()`](https://npmcn.com/package/%40americana/diplomat/#readme-maplibregldiplomatlocalizestyle) 不需要经过 `maplibregl.Map`。只有在将外交官作为脚本时才可用.

示例

```js
map.localizeStyle(["eo"], {
  localizedNamePropertyFormat: "name_$1",
});
```

## 洞穴

外交官只在样式表数据源中存在的语言之间切换。 它不从其他来源获取翻译,也不产生自己的转写. 通过公约, [OpenStreetMap 在一些地区的覆盖率](https://wiki.openstreetmap.org/wiki/Multilingual_names) 主要限于当地通用语言。 如果您需要以特定语言进行更全面的覆盖,请考虑使用一个将 OpenStreetMap 和 Wikidata 名称结合的平板集,例如 [OpenStreetMap 美国梯队服务](https://tiles.openstreetmap.us/vector/openmaptiles/)。 。 。 .

默认情况下,MapLibre GL JS不支持双向文本. 阿拉伯语、希伯来语和其他从右到左的语言,除非你 [安装映射盒- gl- ttl- text 插件](https://maplibre.org/maplibre-gl-js/docs/examples/add-support-for-right-to-left-scripts/)。 。 。 .

外交官根据 [ICU 本地化后退算法](https://unicode-org.github.io/icu/userguide/locale/#fallback)此外,它还执行 [很可能是下级](https://www.unicode.org/reports/tr35/#Likely_Subtags) unicode 技术标准# 35 的算法, 例如请求 `zh` 或者说 `cmn` 返回标记为 `zh-Hans-CN`,以及其他变化。 然而,一般来说,它并不回到一个相关但截然不同的语言代码,例如: `sr-Cyrl` 改为 `ru` 或从 `nb` 改为 `no`。相反,用户可以 [设置首选语言](https://www.w3.org/International/questions/qa-lang-priorities) 在他们的浏览器或操作系统设置中.

出于历史原因, [OpenStreetMap 在许多地区的覆盖范围](https://wiki.openstreetmap.org/wiki/Multilingual_names) 编码以可被人类读取的平分分隔的多个本地名称. 外交官没有试图猜测哪个平分是名字的一部分,哪个平分是两个名字.

## 承认

此插件已弹出 [OpenStreetMap 美国a](https://github.com/osm-americana/openstreetmap-americana/) 项目。 它最初的灵感来自 [地图箱 GL 语言](https://github.com/mapbox/mapbox-gl-language/)。 。 。 .

## 常见问题

### @americana/diplomat 是什么？

MapLibre GL JS 的国际化插件

### 如何安装 @americana/diplomat？

在项目目录运行 npm install @americana/diplomat，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：maplibre-gl（^5\.22\.0 \|\| ^6\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @americana/diplomat 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @americana/diplomat 支持 ESM 还是 CommonJS？

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

### @americana/diplomat 可以商用吗？

@americana/diplomat 使用 CC0-1\.0 许可。作者放弃著作权，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。

### @americana/diplomat 的下载量有多少？

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

### @americana/diplomat 还在维护吗？

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