云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/i18n

查看官方原文 ↗
💡 云策文档标注

概述

@wordpress/i18n 是一个用于客户端本地化的国际化工具包，提供字符串翻译、格式化等功能。它基于 ES2015+ 环境，支持 Jed 格式的本地化数据。

关键要点

  • 安装方式：通过 npm install @wordpress/i18n --save 安装，需确保运行环境支持 ES2015+ 或使用 polyfill。
  • 核心函数：包括 sprintf（字符串格式化）、_n（单复数翻译）、_x（带上下文翻译）、__（基础翻译）等，用于处理多语言文本。
  • API 功能：提供 createI18n（创建实例）、setLocaleData（设置本地化数据）、isRTL（检查 RTL 语言）、subscribe（订阅数据变化）等方法。
  • 数据格式：使用 Jed-formatted JSON 对象来管理本地化数据，支持域（domain）隔离。
  • 相关资源：链接到 Block Editor Handbook 和 WordPress 函数参考，便于深入学习和集成。

代码示例

import { sprintf, _n } from '@wordpress/i18n';
sprintf( _n( '%d hat', '%d hats', 4, 'text-domain' ), 4 );
// 输出: 4 hats

注意事项

  • 环境要求：代码需在 ES2015+ 环境中运行，否则需包含 @wordpress/babel-preset-default 中的 polyfill。
  • 数据管理：使用 setLocaleData 和 resetLocaleData 来操作本地化数据，注意域参数的应用。
  • 贡献方式：此包是 Gutenberg 项目的一部分，遵循 monorepo 结构，贡献者需参考项目主指南。
📄 原文内容

Internationalization utilities for client-side localization. See How to Internationalize Your Plugin for server-side documentation.

Installation

Install the module:

npm install @wordpress/i18n --save

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Usage

import { sprintf, _n } from '@wordpress/i18n';

sprintf( _n( '%d hat', '%d hats', 4, 'text-domain' ), 4 );
// 4 hats

For a complete example, see the Internationalization section of the Block Editor Handbook.

API

createI18n

Create an i18n instance

Parameters

  • initialData [LocaleData< TextDomain >]: Locale data configuration.
  • initialDomain [TextDomain]: Domain for which configuration applies.
  • hooks [Hooks]: Hooks implementation.

Returns

  • I18n< TextDomain >: I18n instance.

defaultI18n

Default, singleton instance of I18n.

getLocaleData

Returns locale data by domain in a Jed-formatted JSON object shape.

Related

Parameters

  • domain [ string | undefined ]: Domain for which to get the data.

Returns

  • LocaleData: Locale data.

hasTranslation

Check if there is a translation for a given string (in singular form).

Parameters

  • single string: Singular form of the string to look up.
  • context string: Context information for the translators.
  • domain string: Domain to retrieve the translated text.

Returns

  • boolean: Whether the translation exists or not.

isRTL

Check if current locale is RTL.

RTL (Right To Left) is a locale property indicating that text is written from right to left. For example, the he locale (for Hebrew) specifies right-to-left. Arabic (ar) is another common language written RTL. The opposite of RTL, LTR (Left To Right) is used in other languages, including English (en, en-US, en-GB, etc.), Spanish (es), and French (fr).

Returns

  • boolean: Whether locale is RTL.

resetLocaleData

Resets all current Tannin instance locale data and sets the specified locale data for the domain. Accepts data in a Jed-formatted JSON object shape.

Related

Parameters

  • data [LocaleData]: Locale data configuration.
  • domain [string | undefined]: Domain for which configuration applies.

setLocaleData

Merges locale data into the Tannin instance by domain. Accepts data in a Jed-formatted JSON object shape.

Related

Parameters

  • data [LocaleData ]: Locale data configuration.
  • domain [string | undefined]: Domain for which configuration applies.

sprintf

Returns a formatted string.

Related

Parameters

  • format T | TransformedText< T >: The format of the string to generate.
  • args DistributeSprintfArgs< T >: Arguments to apply to the format.

Returns

  • TransformedText< T >: The formatted string.

subscribe

Subscribes to changes of locale data

Parameters

  • callback SubscribeCallback: Subscription callback

Returns

  • UnsubscribeCallback: Unsubscribe callback

_n

Translates and retrieves the singular or plural form based on the supplied number.

Related

Parameters

  • single Single: The text to be used if the number is singular.
  • plural Plural: The text to be used if the number is plural.
  • number number: The number to compare against to use either the singular or plural form.
  • domain string | undefined: Domain to retrieve the translated text.

Returns

  • TransformedText<Single | Plural>: The translated singular or plural form.

_nx

Translates and retrieves the singular or plural form based on the supplied number, with gettext context.

Related

Parameters

  • single Single: The text to be used if the number is singular.
  • single Single: The text to be used if the number is singular.
  • plural Plural: The text to be used if the number is plural.
  • number number: The number to compare against to use either the singular or plural form.
  • context string: Context information for the translators.
  • domain [string | undefined]: Domain to retrieve the translated text.

Returns

  • TransformedText<Single | Plural>: The translated singular or plural form.

_x

Retrieve translated string with gettext context.

Related

Parameters

  • text Text: Text to translate.
  • context string: Context information for the translators.
  • domain string | undefined: Domain to retrieve the translated text.

Returns

  • TransformedText<Text>: Translated context string without pipe.

__

Retrieve the translation of text.

Related

Parameters

  • text Text: Text to translate.
  • domain string | undefined: Domain to retrieve the translated text.

Returns

  • TransformedText<Text>: Translated text.

Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.