1k-i18n

name	1k-i18n
description	Internationalization and translation guidelines for OneKey. Use when adding text strings, using translations, or working with locales. Triggers on i18n, translation, locale, intl, formatMessage, ETranslations, language, text.
allowed-tools	Read, Grep, Glob, Bash

OneKey Internationalization (i18n) Guidelines

Translation Management - CRITICAL RESTRICTIONS

ABSOLUTELY FORBIDDEN (These files are AUTO-GENERATED):

• ❌ NEVER modify @onekeyhq/shared/src/locale/enum/translations.ts - Will be overwritten and break i18n system
• ❌ NEVER modify locale JSON files in @onekeyhq/shared/src/locale/json/* - Managed by external translation system
• ❌ NEVER hardcode text strings in components - ALWAYS use translation keys
• ❌ NEVER add translation keys directly to enum files - Use proper workflow

CONSEQUENCES OF VIOLATION:

• Translation system corruption
• Loss of translation work
• Build failures in i18n pipeline
• Breaking localization for international users

Using Translations

• Use useFormatMessage or formatMessage functions for displaying translated text
• Define new translation keys in the appropriate modules
• Always use translation keys instead of hardcoding text strings
• Follow the established pattern for translation keys: namespace__action_or_description

Updating Translation Keys

1. Direct translation from design specs: Update i18n directly based on design spec annotations without searching existing translation keys
2. Run yarn fetch:locale to pull the latest translation keys from the remote system
3. This command automatically updates @onekeyhq/shared/src/locale/enum/translations.ts with new translation enums
4. For design spec translation keys like prime::restore_purchases, convert to code format:
   • Replace :: with _ (underscore)
   • Use the enum: ETranslations.prime_restore_purchases
   • In component code:

     {intl.formatMessage({
       id: ETranslations.prime_restore_purchases,
     })}
     

Locale Handling

• The system uses automatic locale detection with fallbacks
• Default locale fallback chain is implemented in getDefaultLocale.ts
• Respect platform-specific locale handling (web, native, desktop, extension)

Code Examples

Using Translations in Components

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>
  );
}

Using formatMessage Outside Components

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

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

Translation Key Naming Pattern

namespace__action_description

Examples:
- global__confirm
- global__cancel
- swap__select_token
- wallet__create_wallet
- settings__dark_mode