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 - 一般的なコーディングパターン