1k-i18n

国际化（i18n）

OneKey 国际化和翻译管理指南。

关键限制

绝对禁止（自动生成文件）：

// ❌ NEVER modify these files - they are AUTO-GENERATED
// @onekeyhq/shared/src/locale/enum/translations.ts
// @onekeyhq/shared/src/locale/json/*.json

// ❌ NEVER hardcode text strings
<Text>Confirm</Text>

// ✅ CORRECT - Always use translation keys
import { ETranslations } from '@onekeyhq/shared/src/locale';
intl.formatMessage({ id: ETranslations.global__confirm })

违反后果：

• 翻译系统损坏
• 翻译工作丢失
• i18n 流水线构建失败
• 影响国际用户的本地化体验

优先使用现有键

创建键之前，请先在本地和远程搜索。仅当键的含义、占位符和 UI 上下文都一致时，才可复用。

在 Lokalise 中创建或更新任何内容时：

• 修改之前，确认实际目标项目的名称和 ID。
• 获取该项目配置的语言；不要根据环境变量名称推断。
• 优先使用仓库脚本和凭据封装工具。默认使用 yarn op；也支持 keychain 和 oenv 变体。
• 可使用已配置的 Lokalise MCP 或 Lokalise Web 获取现有翻译，但仍须进行相同的项目和语言检查。
• 远程修改后，使用 yarn i18n:pull、yarn i18n:pull:keychain 或 yarn i18n:pull:oenv 同步到本地。

键格式映射

根据查看位置的不同，同一翻译可能呈现为 3 种不同格式：

Lokalise / MCP source key:     global::contact_us
Pulled local JSON key:         global.contact_us
Generated enum member:         ETranslations.global_contact_us

对于较新的后缀式键，Lokalise 和本地 JSON 通常一致：

Lokalise / MCP source key:     address_book__action
Pulled local JSON key:         address_book__action
Generated enum member:         ETranslations.address_book__action

查询指南：

• Lokalise / MCP：优先使用确切的源键。旧版命名空间键通常使用 ::。
• 本地 yarn i18n:search：会搜索拉取的 en_US.json，因此旧版键应使用 . 查询，较新的后缀式键应使用 __ 查询。
• 代码用法：通过 _ 引用生成的 ETranslations 成员。

端到端交付要求

对于任何创建或更新翻译的任务：

1. 在拉取生成文件之前，检查当前分支和工作区。
2. 获取凭据，但不要打印令牌。
3. 获取 GET /projects/{project_id}，并确认返回的项目名称和 ID 与预期目标一致。
4. 获取 GET /projects/{project_id}/languages，并记录准确的 lang_iso 值。
5. 创建键之前，在已验证的项目中搜索确切的键。
6. 缺少键时，使用 yarn i18n:add。此命令只会创建 en_US 和可选的 zh_CN 源翻译；不会完成其余区域设置。
7. 确保每个已纳入版本控制的区域设置都有有效的键翻译。仓库目前有 19 个区域设置 JSON 文件。
8. 拉取生成文件，检查枚举和所有区域设置 JSON 文件，并审查完整的生成差异，确认没有无关的远程更新。
9. 在代码中接入生成的 ETranslations 成员，并验证占位符一致性。

不要仅因目标项目使用了不同的代码格式，就悄悄跳过某个仓库区域设置。请将仓库区域设置名称映射到项目配置的 lang_iso 值。如果项目确实缺少必需语言，请在上传前停止并报告差异。

完成报告必须说明已验证的项目名称/ID、覆盖的区域设置集合、使用的拉取命令、生成文件范围，以及拉取时带入的任何无关键。代码更改和生成的区域设置更改应分别审查。

在执行任何远程 Lokalise 修改或 i18n:pull 之前，请阅读 i18n.md。其中包含项目预检、当前的 19 个区域设置集合、翻译记录更新流程和生成差异验证。

快速参考

在组件中使用翻译

import { useIntl } from 'react-intl';
import { ETranslations } from '@onekeyhq/shared/src/locale';

function MyComponent() {
  const intl = useIntl();

  return (
    <SizableText>
      {intl.formatMessage({ id: ETranslations.global__confirm })}
    </SizableText>
  );
}

在组件外使用 formatMessage

import { appLocale } from '@onekeyhq/shared/src/locale/appLocale';
import { ETranslations } from '@onekeyhq/shared/src/locale';

const message = appLocale.intl.formatMessage({
  id: ETranslations.global__cancel,
});

翻译工作流

1. 先搜索
   • 本地搜索：yarn i18n:search "global.contact_us" 或 yarn i18n:search "address_book__action"
2. 验证目标 — 确认项目名称/ID，并获取项目的准确语言列表
3. 远程搜索 — 在已验证的项目中查询准确的源键，例如 global::contact_us
4. 如果键已存在，请在 Lokalise 中按翻译记录更新
5. 如果是新键，请使用后缀式下划线格式，通过 yarn i18n:add 添加
6. 补全仓库中的所有语言 — 不要在完成 en_US/zh_CN 后就停止
7. 拉取并检查 — 确认该键在所有位置都存在，并指出无关的生成变更
8. 在代码中使用：

   {intl.formatMessage({ id: ETranslations.global_contact_us })}
   

新键命名模式

semantic_key__type

Examples:
- send__title
- confirm_send__action
- enter_send_amount__desc
- transaction_failed__msg

详细指南

如需了解全面的 i18n 指南和端到端的 Lokalise 工作流，请参阅 i18n.md。

涵盖主题：

• 翻译管理限制
• 在组件中使用翻译
• 翻译键命名约定
• 目标项目和语言验证
• 覆盖全部 19 种语言
• 安全的 Lokalise 创建/更新和拉取流程
• 生成的差异检查
• 语言环境处理和回退
• 代码示例

关键文件

用途	文件路径
翻译枚举（自动生成）	packages/shared/src/locale/enum/translations.ts
语言环境 JSON（自动生成）	packages/shared/src/locale/json/
应用语言环境	packages/shared/src/locale/appLocale.ts
默认语言环境	packages/shared/src/locale/getDefaultLocale.ts
Lokalise 添加脚本	development/scripts/i18n/i18n-add.js
Lokalise 拉取脚本	development/scripts/i18n/i18n-pull.js

相关技能

• /1k-coding-patterns - 支持语言环境的日期格式化
• /1k-coding-patterns - 通用编码模式