# ローカリゼーションサービス

<figure><img src="/files/5OIndkUtlHwMuj2KdjIU" alt=""><figcaption></figcaption></figure>

**対象**: IT管理者向けです。本ページでは、**ローカライズサービス**の動作、**ロケール**の決め方と**上書き**方法、ならびにローカライズ構成によるUI文言の**変更**方法について説明します。

***

### 概要

Keeper特権マネージャーでは、トレイアプリやMFA/承認/正当化ダイアログ、メッセージなどのUIコンポーネントについて、**複数言語**を利用できます。次の処理が行われます。

* **ユーザーのロケールの解決** (システム検出または明示的上書き)
* **ユーザーごとの選択ロケールの保持** (ローカルサービスへの登録経由)
* **カルチャ** (例: `en_US`、`fr_FR`) ごとの各コンポーネントへの**ローカライズ済み文字列**の配信
* **ローカライズ用JSONファイル**の編集、または対応環境での**ローカライズAPI**による文言**カスタマイズ**

ロケールは**ユーザー単位** (または登録したセッション単位) です。各UIコンポーネントは**登録済み**カルチャの文字列を要求するため、メニュー、ダイアログ、通知は正しい言語で表示されます。

***

### ロケールの決まり方

#### デフォルトの動作 (上書きなし)

1. **KeeperClient** (トレイ) アプリの起動時に、使用するロケールを決定します。
   * 上書きが構成されていない場合は、**システムロケールの検出**を使います (Windowsの表示言語、Linuxの`LANG`/ロケール、macOSの設定)。
   * 結果は `en_US`、`fr_FR`、`es_ES` (language\_REGION) 形式の**カルチャコード**に正規化されます。
2. クライアントは **`POST /api/Locale/Register`** を呼び出し、`{ "Locale": "en_US" }` のようなJSONボディで、このロケールをKeeper特権マネージャーに**登録**します。
3. サービスは、そのユーザー (またはセッション) のロケールを保存します。同じコンテキストで動くその他のUIアプリ (KeeperMFA、KeeperApproval、KeeperJustification、KeeperMessageなど) は、ローカライズデータを要求するとき**同じ登録済みロケール**を使います。
4. コンポーネントが文字列 (メニューラベル、ダイアログ文言など) を必要とするとき、**`GET /api/localization/{component}/{culture}`** を呼び出します (例: `GET /api/localization/KeeperClientLocales/en_US`)。**カルチャ**は登録済みロケール由来のため、すべてのコンポーネントは同期されます。

したがってデフォルトでは、**システムロケール** → Keeper特権マネージャーへの**登録** → **すべてのUIが当該カルチャ**によるローカライズ、という流れになります。

#### フォールバック

* システム検出失敗時のクライアントによる**en\_US**へのフォールバック
* 文字列ごとに要求したカルチャが欠けている場合の、サービスによる**en\_US**へのフォールバック、またはUIによるフォールバックメッセージの表示 (トーストの `message` フィールドなど)

***

### ロケールの上書き

システムが検出したロケールを**上書き**し、OSの表示言語に関係なくUIで特定の言語を常に使うことができます。

#### 方法1: KeeperClientプラグイン設定 (推奨)

**KeeperClient**プラグインでは、**メタデータ**に**LanguageOverride**を指定できます。

| 設定                            | 型      | デフォルト       | 効果                       |
| ----------------------------- | ------ | ----------- | ------------------------ |
| **metadata.LanguageOverride** | string | `"DEFAULT"` | トレイおよび関連コンポーネントのUI言語の上書き |

**値**:

* **`"DEFAULT"`** (または空/未設定): **システム検出**ロケール (上記の動作)
* **有効なカルチャコード**: 当該言語の強制。例: `"en_US"`、`"fr_FR"`、`"es_ES"`、`"de_DE"`、`"ja_JP"`、`"zh_CN"`

**設定方法**:

1. **ダッシュボードから**: デプロイで構成ポリシーまたはプラグイン設定のプッシュに対応している場合、KeeperClientプラグインの**LanguageOverride**を希望のカルチャコードに設定します。
2. **エンドポイント上で**: KeeperClientプラグインのJSON (例: `Plugins/KeeperClient.json` またはインストールで使うパス) を編集し、`metadata` 配下に次を追加または変更します。

   ```
   "metadata": {
     "LanguageOverride": "fr_FR"
   }
   ```

   その後、**KeeperClient**プラグイン (またはエージェント) を**再起動**し、設定を再読み込みします。次回起動時、KeeperClientは `LanguageOverride` を読み取り、システム検出の代わりに `fr_FR` を使い、`POST /api/Locale/Register` で登録します。

**注**: 値が有効なカルチャコードでない場合、クライアントは警告をログに記録し、システム検出にフォールバックします。

#### 方法2: APIでロケールを登録する

管理者またはカスタムスクリプトが、 **`POST /api/Locale/Register`** を `{ "Locale": "fr_FR" }` のようなボディ (適切な認証、通常は対象ユーザー/セッションのコンテキスト) で呼び出せます。これによりそのユーザーの保存ロケールは**上書き**され、以降のUIコンポーネントは新しいカルチャの文字列を要求します。高度な操作であり、通常はプラグイン設定またはコマンドライン上書きを使います。

#### まとめ

| 方法                                           | 範囲                          | 永続性             |
| -------------------------------------------- | --------------------------- | --------------- |
| **metadata.LanguageOverride** (KeeperClient) | 当該構成が適用されるエンドポイント上のすべてのユーザー | 構成変更とプラグイン再起動まで |
| **--language-override** (起動引数)               | 単一プロセスの実行                   | その実行のみ          |
| **POST /api/Locale/Register**                | 1ユーザー/セッション                 | 次回の登録まで         |

***

### 文言の変更方法 (ローカライズ構成)

**ローカライズデータ**を編集すると、UIに表示される**文言を変更**できます。**文字列キー**と**カルチャ別の文言**の対応は**ロケールファイル** (JSON) に保持されます。ファイルを直接編集するか、**ローカライズAPI**を使います。

#### ローカライズデータの場所

* **サービス (エージェント) 上**: ローカライズ用JSONファイルは通常、Keeper特権マネージャーインストール内の**Localization**ディレクトリ配下 (正確なパスはデプロイ依存。例: `KeeperPrivilegeManager/Localization/`)。
* **コンポーネント別ファイル**: 各UIコンポーネントごとのロケールファイル (または共有)。例:
  * **LocaleValues.json**: コア/システム文字列
  * **SharedLocales.json**: 共有文字列 (ボタン、共通ラベルなど)
  * **KeeperClientLocales.json**: トレイアプリ (KeeperClient)
  * **KeeperMfaLocales.json**: MFAダイアログ
  * **KeeperApprovalLocales.json**: 承認ダイアログ
  * **KeeperJustificationLocales.json**: 正当化ダイアログ
  * **KeeperMessageLocales.json**: KeeperMessageダイアログ
  * **KeeperTrayLocales.json**: システムトレイ
  * **KeeperControlsLocales.json**: コントロールUI
  * **SudoWrapperLocales.json**、**DiagnosticToolLocales.json**: CLI/ツール向け文字列

APIの**コンポーネント名** (`GET /api/localization/{component}/{culture}`) は、これらのファイルに対応します (例: `KeeperClientLocales`、`SharedLocales`)。

<mark style="color:$danger;">**警告**</mark>: アップグレード時にローカライズファイルが上書きされる場合があります。

#### ローカライズファイルのJSON構造

各ファイルは、次のようなJSONオブジェクトです。

* **キー**: コードまたはジョブで使う文字列ID (例: `kepm_kc_menu_settings`、`kepm_shared_button_ok`)
* **値**: **カルチャコード**から**表示文言**へのマッピングオブジェクト

**例**

```
{
  "kepm_shared_button_ok": {
    "en_US": "OK",
    "fr_FR": "OK",
    "es_ES": "Aceptar",
    "de_DE": "OK"
  },
  "kepm_approval_title": {
    "en_US": "Approval Required",
    "fr_FR": "Approbation requise",
    "es_ES": "Aprobación requerida"
  }
}
```

**パラメータ付き文字列**はプレースホルダ `{0}`、`{1}` などを使います。例: `"en_US": "Approval required for {0}"`。アプリは実行時に値を代入します。

**カルチャコード**は**language\_REGION**形式です (例: `en_US`、`fr_FR`、`zh_CN`)。製品は en\_US、en\_GB、es\_ES、fr\_FR、de\_DE、it\_IT、pt\_BR、ja\_JP、ko\_KR、zh\_CN、zh\_TW、ru\_RU など、多数のロケールを扱えます。対象とするロケールに合わせてカルチャキーを追加または編集してください。

#### ローカライズファイルの編集による文言変更

1. **正しいファイルの特定**: トレイ/メニュー文言には**KeeperClientLocales.json**または**SharedLocales.json**。MFA/承認/正当化/メッセージのダイアログには、対応するコンポーネントファイル (例: **KeeperMfaLocales.json**、**KeeperApprovalLocales.json**)。
2. **キーの検索**: キーは `kepm_kc_*` (KeeperClient)、`kepm_shared_*` (共有)、`kepm_kmfa_*` (MFA)、`kepm_kapproval_*` (承認) などのパターンに従います。変更したい文言に対応するキーを検索します (拡張する場合は新規キーを追加し、既存エントリと同じ構造にします)。
3. **カルチャ別の値の編集**: 目的のカルチャの文字列を変更します (例: `"en_US": "Your new text"`)。ファイルにまだそのロケールがない場合は、新しいカルチャブロックを追加できます。
4. **ファイルの保存と再読み込み**: ファイルを保存し、変更をサービスが読み込むよう再読み込みします。
   * **影響を受けるプラグイン** (例: KeeperClient) の**再起動**または**エージェントの再起動**、および/または
   * デプロイで**ロケールキャッシュ**を使っている場合の**locale-cache-cleanup**ジョブ (または同等の処理) の実行 (次の要求で最新データの取得)

**重要**:

* 有効なJSONの維持 (カンマ、引用符)
* 編集前のファイルのバックアップ
* アプリ参照中キーの削除禁止 (キー欠落プレースホルダ表示のリスク)

#### ローカライズAPIによる文言の変更 (管理者)

ローカライズ文字列の作成、更新、削除向けの**管理者**用エンドポイントが公開されています。

| メソッド       | パス                                | 説明                             |
| ---------- | --------------------------------- | ------------------------------ |
| **POST**   | `/api/localization/strings`       | ローカライズ文字列の作成 (ボディ: キーとカルチャ別の値) |
| **PUT**    | `/api/localization/strings/{key}` | 既存文字列の更新                       |
| **DELETE** | `/api/localization/strings/{key}` | 文字列の削除                         |

これらは通常、`GET /api/localization/{component}/{culture}` への応答に使われる**同一データ**を操作します。ファイルベースのロケールファイルへの反映か別ストアかは実装依存です。製品ドキュメントまたはAPIドキュメントをご参照ください。変更後は**関連するUIの再起動**または**ロケールキャッシュのクリア**を行い、クライアントが更新後の文言を読み込むようにします。

**例 (概念)**: キー `kepm_shared_button_ok` の英語文言を変えるには、更新後の `en_US` 値を含むPUTボディを送ります。正確なリクエスト/レスポンス形式は製品のAPI仕様に従います。

#### 新しいキーまたは新しいカルチャの追加

* **新しいキー**: 適切なJSONファイルに、同じ構造の新しいトップレベルキー (キー名 → カルチャコードと文字列のオブジェクト)。一貫した命名規則 (例: `kepm_<component>_<description>`)。UIまたはジョブ (トーストの`messageKey`など) による参照時の、指定文言の表示。
* **新しいカルチャ**: 既存 (または新規) のキーオブジェクトへの新しいプロパティの追加。例: `"pt_PT": "Texto em português"`。製品で利用可能なロケールかどうかの確認 (またはデプロイで使うカスタムコードの文書化)。

#### 命名規則とベストプラクティス

* **キー命名**: 多くのキーは `kepm_shared_*`、`kepm_kc_*`、`kepm_kmfa_*` などのプレフィックス。同様のスタイルの維持 (検索・保守のしやすさ)。
* **フォールバック**: カルチャ欠落時のデフォルトとして、少なくとも**en\_US**の用意。
* **パラメータ付き文字列**: 動的部分 (ファイル名、件数など) への `{0}`、`{1}` の使用。アプリによる順次代入。
* **テスト**: ファイルまたはAPIの変更後、ユーザーのロケールを当該カルチャに設定 (例:**LanguageOverride**経由) し、UIの再起動と新しい文言の確認。

***

### ロケール登録とローカライズAPIの概要

| 項目           | 説明                                                                                                                                                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ロケールの設定**  | デフォルトはシステム検出。任意の上書きは**metadata.LanguageOverride** (KeeperClient)、**--language-override**、または**POST /api/Locale/Register**                                                                                                                        |
| **ロケールの上書き** | KeeperClientプラグイン構成での**LanguageOverride**をカルチャコード (または `DEFAULT`) に設定し、プラグインの再起動。またはそのユーザー向けの**POST /api/Locale/Register**                                                                                                                       |
| **文言の変更**    | 適切な**Localization/\*.json**の編集 (キー → カルチャ → 文言)。または**POST/PUT/DELETE /api/localization/strings** (管理者)。変更後のUI再起動またはロケールキャッシュのクリア                                                                                                                 |
| **ロケールファイル** | サービス**Localization**ディレクトリ配下の**LocaleValues**、**SharedLocales**、**KeeperClientLocales**、**KeeperMfaLocales**、**KeeperApprovalLocales**、**KeeperJustificationLocales**、**KeeperMessageLocales**、**KeeperTrayLocales**、**KeeperControlsLocales**など |
| **構造**       | `"key": { "en_US": "text", "fr_FR": "text", ... }`。パラメータ付き文字列での `{0}`、`{1}` の使用                                                                                                                                                                  |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/jp/endpoint-privilege-manager/reference/localization-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.