@amazon-devices/keplerscript-kepleri18n-lib

Kepler国际化 (i18n) API可在您的应用中启用本地化功能。

备注

作为最佳实践，可将用户界面消息存储在不属于源代码的资源文件中。Asset Resolver API使应用能够在Vega中管理外部字符串资源。API定义了资源文件格式和字符串资源文件在应用源目录中的预期位置。应用可以使用此API来检索与设备区域设置相匹配的本地化字符串，从而确保用户看到以其首选语言显示的用户界面消息。

开始使用

设置

将以下库依赖项添加到package.json文件的dependencies部分。

用法

以下各部分介绍如何使用Asset Resolver和国际化API。

定义资源文件

第一步是创建资源文件，您将在其中存储字符串资源。您创建和拥有的资源文件是供采用源语言的文本使用的。字符串资源文件格式为PUFF-J。如需更多详细信息和具体的PUFF-J示例，请参阅PUFF-J页面。

需要记住的一些规则和最佳实践：

1. 资源文件的文件扩展名为.puff.json。典型的PUFF-J资源文件名为strings.puff.json。
2. PUFF-J文件中资源ID的字符集仅限于字母数字、下划线、连字符和冒号。该规则目前尚未执行，但将在不久的将来生效。
3. 最佳实践是对资源ID进行描述性命名，以便它们标识资源的使用位置和资源的用途。例如，对于用作WiFi设置对话框标题的字符串资源，ID可以是“wifi-setup-dialog-title”。
4. 在note属性中为资源加入足够的上下文。特别是对于具有占位符的字符串，请提供有关占位符是什么的上下文以及占位符的示例值。
5. 您可以将字符串资源组织成多个PUFF-J文件。请记住，PUFF-J文件中定义的资源键在应用中所有PUFF-J文件的整个集合中必须是唯一的。如果您创建多个PUFF-J文件，请考虑使用应用名称和文件名作为资源键前缀。这样可以更易于保证资源键的唯一性。

PUFF-J文件示例：

示例中的字符串"Wi-Fi已成功连接。网络: {ssid}"采用的是经典的消息格式模式。对于包含在运行时替换的占位符的字符串资源，请勿连接字符串来形成完整的消息。脱离上下文翻译字符串片段然后将它们连接起来，会导致整个消息的翻译不正确。Vega提供了一种消息格式解决方案，您可以使用该解决方案将完整的消息写成经典的消息格式模式。通过该解决方案，翻译者可以查看和翻译完整的消息。有关使用MessageFormatClassic API和指定模式的信息，请参阅消息格式指南。

PUFF-J还支持许多资源。数字资源以双浮点类型表示。

资源文件在源存储库中的位置

将应用源语言PUFF-J文件直接放在assets/text/子目录中。这些是本地化提供方从中提取字符串进行翻译的源文件。将已本地化的PUFF-J文件置于相应的assets/text/<BCP-47语言标签>/子目录中。

BCP-47使用连字符作为子标签分隔符，例如en-US，而不是下划线，下划线由POSIX平台用于在区域设置ID中分隔语言和地区字段。

en-US PUFF-J文件符号链接

如果根/源语言PUFF-J文件使用美式英语，而en PUFF-J文件使用英式英语，则添加en-US子文件夹，并在en-US子文件夹下添加符号链接，链接到相应的根PUFF-J文件（可以参见下面的示例子目录树：mkdir assets/text/en-US; cd assets/text/en-US; ln -s ../strings.puff.json strings.puff.json）。这是为了确保在en-US区域设置中，先于采用英式英语的en PUFF-J文件检索采用美式英语的根PUFF-J文件。

示例assets/text/子目录树：

确保资产目录包含在或复制到源目录中，即VPT打包工具创建应用程序包所在的源目录。对于适用于Vega的React Native应用，构建工具可以执行这个任务。

用于检索资源文件中定义的资源的API

使用Asset Resolver API检索PUFF-J文件中定义的资源。

以下示例展示了如何调用AssetResolver。

当字符串资源的文本基础方向可能与文本用户界面小组件的默认文本基础方向不同时，将字符串资源的dir属性设置为文本用户界面小组件。例如，如果在英语用户界面中显示阿拉伯语字符串资源，则将文本用户界面小组件的文本基础方向属性设置为此dir属性值，该值为阿拉伯语PUFF-J资源文件中设置的rtl（从右到左）。

对于选择和复数字符串资源类型，AssetResolver.getString() 将资源作为经典消息格式模式字符串返回。有关资源类型的更多信息，请参阅“PUFF-J文件格式”主题中的资源类型。

有关使用MessageFormatClassic类和返回的模式字符串来生成格式化字符串的信息，请参阅消息格式指南。

字符串格式

消息格式

面向用户的消息可以在运行时填写名称、数字、日期和时间等变量。本地化消息翻译通常根据目标语言的语法采用不同的字词排序。因此，翻译者必须能够在消息的译文中移动变量。翻译者只有在获得带有变量占位符的完整消息时才能这样做。根据源语言语法连接短语会致使消息无法翻译。Vega提供了一种消息格式解决方案，该解决方案为消息中的变量提供了占位符。开发者可以使用这种消息格式模式以本地化友好的方式编写整个消息。

MessageFormatClassic类采用传统的ICU MessageFormat模式。如需模式教程和参考，请参阅经典ICU MessageFormat指南（仅提供英文版）。自经典的ICU MessageFormat模式出现以来，最佳实践已经发生了几次变化。其中最重要的变化是使用命名参数，而不是编号或位置参数。请使用命名参数示例作为参考。并将MessageFormatClassic类结合相关模式使用，不要照搬所示代码示例中的内容。

注意：​ Unicode有一个工作组起草新的消息格式标准。标准发布后，我们将对其进行审查以将其纳入Vega。

MessageFormatClassic支持模式中占位符的命名参数样式和编号参数样式。推荐使用命名参数样式，因为使用描述性命名占位符时，开发者和翻译者都能因为可读性提高而受益，并且可以更好地推断出模式中占位符中会出现什么样的值。

使用适用于Vega的React Native中的消息格式

以下过程展示了如何使用MessageFormatClassic类：

1. 从@amazon-devices/keplerscript-kepleri18n-lib程序包中导入MessageFormatClassic。

   复制代码 已复制到剪贴板。

    import { MessageFormatClassic } from '@amazon-devices/keplerscript-kepleri18n-lib';
   

2. 要在MessageFormatClassic类中使用命名参数样式模式，可构造一个JavaScript内置Map对象，并在该对象中填充参数名称及其对应值。然后将填充的Map实例和模式传递至MessageFormatClassic.format() 方法。

   使用命名参数样式模式而不是编号参数样式模式，如以下示例所示。

   复制代码 已复制到剪贴板。

    import { MessageFormatClassic } from '@amazon-devices/keplerscript-kepleri18n-lib';
    ...
        // 从字符串资源中检索模式。为了简化示例，在此对其进行了硬编码。
        const pattern: string = "车号 {carNumber} 赢了！ 恭喜您，{driverName}！";
        const carNumber: number = 3;
        const driverName: string = "Alice";
        const argMap = new Map<string, number | string | Date>();
        argMap.set("carNumber", carNumber);
        argMap.set("driverName", driverName);
        const message: string | null = MessageFormatClassic.format(pattern, argMap);
        if (message === null) {
            // 错误
            return;
        }
        // 消息是 "3号车赢了！ 恭喜您，Alice！"。
   

3. 要在MessageFormatClassic类中使用编号参数样式模式，可调用MessageFormatClassic.formatPositional() 方法，按编号参数顺序传递模式和参数值。例如，在提供参数值时，模式参数之后的第一个值对应于{0}，然后是{1}的值，依此类推。

   以下示例展示了如何使用编号参数样式模式。

   复制代码 已复制到剪贴板。

    import { MessageFormatClassic } from '@amazon-devices/keplerscript-kepleri18n-lib';
    ...
        // 从字符串资源中检索模式。为了简化示例，在此对其进行了硬编码。
        const pattern: string = "车号 {0} 赢了！ 恭喜您，{1}!";
        const carNumber: number = 11;
        const driverName: string = "Bob";
        const message: string | null = MessageFormatClassic.formatPositional(pattern, carNumber, driverName);
        if (message === null) {
            // 错误
            return;
        }
        // 消息是"车号11赢了！ 恭喜您，Bob！"。
   

测量单位

要格式化测量单位，例如温度、距离、速度、功率、扭矩、压力，可使用前面所述消息格式，其在模式中带有测量单位框架：

• 使用经典ICU MessageFormat模式指定框架
• 数字框架，其包括对测量单位格式的支持。
• Unicode CLDR中可用的测量单位

以下是带有测量单位框架的传统ICU MessageFormat模式的示例。

经过的时间/持续时间

在适用于Vega的React Native中，有ECMAScript Intl.DurationFormat对象（第3阶段提案）可用。API文档和示例可在Mozilla MDN Web Docs获取（仅提供英文版）。TC39 API提案已在GitHub上提供（仅提供英文版）。

按字母顺序和自然顺序/排序规则排序

在适用于Vega的React Native中，有ECMAScript Intl.Collator对象可用。API文档和示例可在Mozilla MDN Web Docs获取。

应用和系统的区域设置和时区首选项

I18nManager提供检索、修改应用区域设置和时区首选项和侦听其更改的功能。有关API的更多信息，请参阅适用于Vega的React Native国际化和本地化API中的I18nManager部分。

模块

• MessageFormatClassic
• ProductNameFormat

---

Last updated: 2025年9月29日