设置播放器界面语言（国际化）--视频点播-火山引擎

文档中心

立即注册

视频点播

进阶功能

设置播放器界面语言（国际化）

多语言（国际化）功能允许您自定义或切换播放器界面所有可见文本的语言，例如播放/暂停按钮的提示、错误信息、清晰度选项等。

使用内置语言

Web 播放器 SDK 内置了以下四种语言：

简体中文 (zh)
繁体中文 (zh-hk)
英文 (en)
日文 (jp)

如果您在初始化播放器时不指定 lang 参数，SDK 将按以下顺序自动选择语言：

当前网页 <html> 标签的 lang 属性。
浏览器的默认语言设置。
如果以上方式均未匹配到内置语言，则默认使用简体中文 (zh)。

如果您想要指定一种内置语言，只需在初始化播放器时配置 lang 参数。

const playerSdk = new VePlayer({
  id: 'player-container',
  lang: 'en', // 将界面语言设置为英文
  // ... 其他配置
});

自定义界面文案

除了使用内置语言，您还可以添加新的语言支持，或者仅修改特定语言的某些文案。

添加新语言

如果您想支持一种全新的语言（例如，韩语），请参考以下步骤：

定义语言包：创建一个 JavaScript 对象，用于存放自定义的翻译文本。其中，键（Key）是 SDK 预设的标识，值（Value）是您要显示的文本。
```
const koreanLangPack = { 
  PLAY_TIPS: '재생',// 对应“播放”
  PAUSE_TIPS: '일시정지', // 对应“暂停”
  REPLAY: '다시보기',// 对应“重播”
  // ... 其他需要翻译的文案
};
```
说明
完整的文案 Key 列表请参见文末的【附录：文案 Key 列表】。

注册并使用新语言：在初始化播放器时，通过 languages 参数注册您的语言包，并通过 lang 参数指定使用该语言。

const playerSdk = new VePlayer({
  id: 'player-container',
  // ... 其他配置
  lang: 'ko', // 1. 指定使用 'ko' 语言
  languages: {
    'ko': koreanLangPack // 2. 注册 'ko' 语言包
  },
});

配置完成后，播放器上的相关文案（如播放按钮的鼠标悬浮提示）将显示为您在 koreanLangPack 中定义的韩语文本。以画中画按钮文案为例，配置后文案显示成了指定的文案：

修改内置语言的文案

如果您只是想修改某个内置语言（如英语）的个别文案，操作与添加新语言类似。在 languages 参数中，使用内置语言的 Key（例如 en），并只提供您想覆盖的文案。
在以下示例中，播放器将使用内置的英文文案，但“重播”按钮的文本会从默认的 Replay 变为 Play Again。

const player = new VePlayer({
  id: 'player-container',
  // ... 其他配置
  lang: 'en',
  languages: {
    en: {
      // 仅覆盖英文的“重播”按钮文案
      REPLAY: 'en_Play', 
    },
  },
});

以覆写播放按钮文案为例，默认文案为play，配置后显示为en_play。

自定义清晰度文案

清晰度选项（如“高清”、“标清”）的文案也由多语言系统管理。配置方式因播放模式而异。

DirectURL 模式

在 DirectURL 模式下，您需要在 playList 数组的每个清晰度对象中，通过 definitionTextKey 字段指定其对应的语言 Key。

// 假设已定义了包含 'HD' 和 'SD' 的语言包
const myLangPack = {
  // ...
  HD: '高清',
  SD: '标清',
};

const player = new VePlayer({
  id: 'player-container',
  playList: [
    {
      url: '...',
      definition: 'hd',
      definitionTextKey: 'HD', // 对应语言包中的 'HD'
    },
    {
      url: '...',
      definition: 'sd',
      definitionTextKey: 'SD', // 对应语言包中的 'SD'
    },
  ],
  lang: 'my-lang',
  languages: {
    'my-lang': myLangPack,
  },
});

Vid 模式

在 VID 模式下，映射关系在 getVideoByToken 的 definitionMap 字段中配置。definitionMap 的键是服务端返回的清晰度标识（如 720p），值对象中的 definitionTextKey 则指定其对应的语言 Key。

// 假设已定义了包含 'HD_720P' 和 'SD_480P' 的语言包
const myLangPack = {
  // ...
  HD_720P: '高清 720P',
  SD_480P: '标清 480P',
};

const player = new VePlayer({
  id: 'player-container',
  getVideoByToken: {
    playAuthToken: '...',
    definitionMap: {
      '720p': {
        definition: 'hd',
        definitionTextKey: 'HD_720P', // 对应语言包中的 'HD_720P'
      },
      '480p': {
        definition: 'sd',
        definitionTextKey: 'SD_480P', // 对应语言包中的 'SD_480P'
      },
    },
  },
  lang: 'my-lang',
  languages: {
    'my-lang': myLangPack,
  },
});

注意

definitionMap 中可用的清晰度键（如 240p、360p、480p、720p、1080p 等）取决于您的视频媒资实际转出的码流规格，以及您在服务端生成 playAuthToken 时允许的清晰度参数。

参考信息

文案 Key 列表

下表列出了您可以自定义的所有文案 Key 及其用途。

Key	默认英文文案	描述
控件与提示
`PLAY_TIPS`	Play	播放按钮（▶）的悬浮提示。
`PAUSE_TIPS`	Pause	暂停按钮（❚❚）的悬浮提示。
`REPLAY`	Replay	播放结束后显示的重播按钮文本。
`FULLSCREEN_TIPS`	Enter Fullscreen	进入全屏按钮的悬浮提示。
`EXITFULLSCREEN_TIPS`	Exit Fullscreen	退出全屏按钮的悬浮提示。
`CSSFULLSCREEN_TIPS`	Enter Page Fullscreen	进入网页全屏按钮的悬浮提示。
`EXITCSSFULLSCREEN_TIPS`	Exit Page Fullscreen	退出网页全屏按钮的悬浮提示。
`PIP`	Picture in Picture	进入画中画按钮的悬浮提示。
`DEFINITION_AUTO`	Auto	清晰度列表中的“自动”选项。
错误信息
`NETWORK`	Network error	通用网络错误提示。
`NETWORK_TIMEOUT`	Network timeout	网络连接超时。
`NETWORK_FORBIDDEN`	The video URL is prohibited from access. Please check the domain name access control.	视频 URL 禁止访问（例如，域名访问控制）。
`NETWORK_NOTFOUND`	The video not found, please check whether the URL is correct.	视频资源未找到（404）。
`NETWORK_RANGE_NOT_SATISFIABLE`	The request range is incorrect, please try again later.	请求范围错误。
`NETWORK_PROTOCOL`	The request protocol is incorrect, please use the https URL to access.	请求协议错误（例如，在 https 页面请求 http）。
`NETWORK_URL_EXPIRE`	The video URL has expired.	视频 URL 已过期。
`NETWORK_URL_SIGN`	The video URL signature is incorrect, please check whether the URL is correct.	视频 URL 签名错误。
`MEDIA_ERR`	Media error	通用媒体错误。
`MEDIA_ERR_ABORTED`	Playback was canceled by the user or browser.	用户或浏览器取消了播放。
`MEDIA_ERR_NETWORK`	Network error.	媒体相关的网络错误。
`MEDIA_ERR_DECODE`	Decoding error.	解码错误。
`MEDIA_ERR_SRC_NOT_SUPPORTED`	Audio/Video format not supported or URL unavailable.	音视频格式不支持或 URL 不可用。
`MEDIA_ERR_NOT_SUPPORTED`	Unsupported video format.	不支持的视频格式。
`MEDIA_ERR_URL_EMPTY`	Video URL is empty.	视频 URL 为空。
`MEDIA_ERR_FILE_NOT_SUPPORTED`	Video file is not supported in the current browser environment.	当前浏览器环境不支持该视频文件。
`MEDIA_ERR_PLAY_ERR`	Video playback error.	视频播放时发生错误。
`MEDIA_SOURCE_CANNOT_PLAY_TYPE`	Unsupported video type.	MSE 模式下不支持的视频类型。
`OTHER`	Other error.	其他未知错误。
`PLAY_AUTH_TOKEN_EXPIRED`	playAuthToken has expired.	播放凭证（playAuthToken）已过期。

最近更新时间：2026.03.18 13:51:28

这个页面对您有帮助吗？

有用

无用

视频点播

使用内置语言 #

自定义界面文案 #

添加新语言 #

修改内置语言的文案 #

自定义清晰度文案 #

DirectURL 模式 #

Vid 模式 #

参考信息 #

文案 Key 列表 #