メッセージ - グローバル

Message Server API を使用すると、code パラメーターに等しいコード、message パラメーターに等しいキー、およびセッションの言語 (またはフォールバック言語) に等しい言語を持つエントリのメッセージ [sys_ui_message] テーブルからローカライズされたメッセージを取得できます。

Message API は、ユーザーのセッション言語または指定された言語パラメーターに基づいてメッセージを動的にフェッチすることで、インターナショナリゼーション (i18n) をサポートします。この API には、次の 3 つの主な機能があります。

• 曖昧性除去: コード と メッセージの 複合キーを使用して、異なるコンテキストで使用される同一の文字列を区別します(たとえば、動詞と名詞としての「open」)。
• 名前付きパラメーター: 名前付きプレースホルダーを使用して、値をメッセージテンプレートに動的に補間できます。
• 言語制御: getMessageLang を使用すると、ターゲット言語を指定でき、差し込み印刷や多言語通知などのシナリオに役立ちます 2 3.

メッセージ API は、sn_i18n 名前空間内の標準ベースシステムで提供され、アクセスするためにプラグインや特別なロールは必要ありません。このクラス内のメソッドを呼び出す前に、適切なメッセージ [sys_ui_message] レコードが存在し、一致する キー フィールドと コード フィールドが入力されていることを確認してください。

Message.getMessage(String code, String message, Map args)

曖昧性除去と動的なコンテンツ挿入を可能にしながら、メッセージ [sys_ui_message] テーブルからローカライズされたメッセージを取得します。

API は翻訳者向けのインラインコメントをサポートし、多言語コンテキストでの明確さを高め、あいまいさを軽減します。コメントはメッセージ [sys_ui_message] のキーフィールドでは使用されませんが、コメントされた文字列を [commented_message] フィールドに追加できます。args パラメーターの値は、文字列内の一致するテンプレートリテラルに補間されます。

表 : 1. パラメーター

名前	タイプ	説明
コード	文字列	必須。類似したテキストで意味やコンテキストが異なるメッセージを区別するための曖昧性除去キー。文字列がスコープ内で一意である場合は、スコープ名を使用できます。さらに曖昧さ回避が必要な場合は、拡張することができます。 たとえば、「オープン」はステータスまたはアクションを意味する場合があり、コードパラメーターはどちらであるかを明確にするのに役立ちます。同じ文字列で大文字と小文字が異なる 2 つのメッセージが必要な場合、スクリプトは次のようになります。 sn_i18n.Message.getMessage("scopeName-open-capitalized", "Open"); sn_i18n.Message.getMessage("scopeName-open", "open");
メッセージ	文字列	オプション。ローカライズされたバージョンが見つからない場合に使用するデフォルトのメッセージ文字列。メッセージ [sys_ui_message] テーブルの キー フィールドに対応します。
引数	JSON	オプション。メッセージを動的に値を挿入するために使用される名前付きパラメーターのマップ。キーは、メッセージ内の名前付きパラメーターと一致します。値は、スコープ内にある文字列リテラルまたは変数/定数にすることができます。 たとえば、メッセージが "Hello, ${John}!" の場合、{name: "John"} を渡して "Hello, John!" をレンダリングできます。

表 : 2. 返される内容

タイプ	説明
文字列	メッセージ [sys_ui_message] テーブルから値を返します。 メッセージパラメーターの最初の 255 文字がキーフィールドと一致します。 コードパラメーターの最初の 255 文字がコードフィールドと一致します。 言語フィールド (言語フィールドが指定されていない場合はセッション言語) が言語フィールドと一致します。 一致するものが見つからない場合は、代替言語の一致がチェックされます ( Set a fallback language を参照)。それでも一致が見つからない場合は、メッセージ値 (2 番目のパラメーター) が返され、コメントが削除されます。 名前付きパラメーターは、args パラメーターで渡されたマップ内の指定された値に置き換えられます。

次の例では、getMessage() メソッドを呼び出して、メッセージ [sys_ui_message] テーブル内の既存のレコードをフランス語 (ユーザーセッション言語) であいまいさを取り除きます。次のコードブロックには、メッセージの内容が含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<xml>
	<sys_ui_message>
		<code>exampleCode</code>
		<key>User {username} has been added as {role}</key>
		<language>fr</language>
		<message>L'utilisateur {username} a été ajouté en tant que {role}</message>
	</sys_ui_message>
</xml>

この例では、フランス語のセッション言語で API スクリプトを実行します。

//defines a user object using the name and role properties
var user = {
name: "Fred Luddy",
role: "maint"
}

//retrieves a localized message where code: "exampleCode" is the disambiguation key, message: User {username} has been added as {role}" is the default message template, and args: username: user.name, role: user.role } is a map of named parameters that will replace {username} and {role} in the message.
gs.info(sn_i18n.Message.getMessage("exampleCode","User {username} has been added as {role}",{username: user.name, role: user.role}));

出力には、フランス語のメッセージが含まれています。

//English: User Fred Luddy has been added as maint
L'utilisateur Fred Luddy a été ajouté en tant que maint

名前付きパラメーターなしの基本的な使用法

// Retrieves a localized message using only code and default message
var message = sn_i18n.Message.getMessage("status.open", "Open");
gs.info(message); // Output depends on user's session language

この例では、 code ("satus.open") を使用してメッセージを明確にし、翻訳が見つからない場合のフォールバックとして message ("Open") を使用しています。

名前付きパラメーターの基本的な使用法

/ Retrieves a localized message with named parameters
var message = sn_i18n.Message.getMessage(
  "greeting.personal",
  "Hello, ${name}! You have ${count} new messages.",
  { name: "John", count: 5 }
);
gs.info(message); // Output: "Hello, John! You have 5 new messages." (localized if available)

この例では、 code ("greeting.personal") を使用してこの挨拶を他の挨拶と区別し、 message はプレースホルダーを含むテンプレートです。 args ({name: "John", count: 5}) はプレースホルダーを埋めます。

Message.getMessageLang(文字列コード, 文字列メッセージ, マップ引数, 文字列言語)

現在のユーザーのセッション言語に関係なく、指定された言語でメッセージ [sys_ui_message] 内のローカライズされたメッセージを取得します。

API は翻訳者向けのインラインコメントをサポートし、多言語コンテキストでの明確さを高め、あいまいさを軽減します。コメントはメッセージ [sys_ui_message] のキーフィールドでは使用されませんが、コメントされた文字列を [commented_message] フィールドに追加できます。args パラメーターの値は、文字列内の一致するテンプレートリテラルに補間されます。

getMessageLang() は次の場合に役立ちます。

• セッション言語の上書き:特定の言語で通知、メール、またはレポートを送信する場合に便利です。
• 多言語サポート:さまざまな地域のユーザーにサービスを提供するアプリケーションに最適です。
• 翻訳のテスト:開発者は、ユーザー設定を変更せずに、他の言語でメッセージがどのように表示されるかをプレビューできます。

表 : 3. パラメーター

名前	タイプ	説明
コード	文字列	必須。類似したテキストで意味やコンテキストが異なるメッセージを区別するための曖昧性除去キー。文字列がスコープ内で一意である場合は、スコープ名を使用できます。さらに曖昧さ回避が必要な場合は、拡張することができます。 たとえば、「オープン」はステータスまたはアクションを意味する場合があり、コードパラメーターはどちらであるかを明確にするのに役立ちます。同じ文字列で大文字と小文字が異なる 2 つのメッセージが必要な場合、スクリプトは次のようになります。 sn_i18n.Message.getMessage("scopeName-open-capitalized", "Open"); sn_i18n.Message.getMessage("scopeName-open", "open");
メッセージ	文字列	オプション。ローカライズされたバージョンが見つからない場合に使用するデフォルトのメッセージ文字列。メッセージ [sys_ui_message] テーブルの キー フィールドに対応します。
引数	JSON	オプション。メッセージを動的に値を挿入するために使用される名前付きパラメーターのマップ。キーは、メッセージ内の名前付きパラメーターと一致します。値は、スコープ内にある文字列リテラルまたは変数/定数にすることができます。 たとえば、メッセージが "Hello, ${John}!" の場合、{name: "John"} を渡して "Hello, John!" をレンダリングできます。
言語	文字列	オプション。メッセージを返す言語。 形式: BCP-47 言語コード デフォルト:セッション言語

表 : 4. 戻り値

タイプ	説明
文字列	メッセージ [sys_ui_message] テーブルから値を返します。 メッセージパラメーターの最初の 255 文字がキーフィールドと一致します。 コードパラメーターの最初の 255 文字がコードフィールドと一致します。 言語フィールド (言語フィールドが指定されていない場合はセッション言語) が言語フィールドと一致します。 一致するものが見つからない場合は、代替言語の一致がチェックされます ( Set a fallback language を参照)。それでも一致が見つからない場合は、メッセージ値 (2 番目のパラメーター) が返され、コメントが削除されます。 名前付きパラメーターは、args パラメーターで渡されたマップ内の指定された値に置き換えられます。

次の例では、getMessageLang() メソッドを呼び出して、メッセージ [sys_ui_message] テーブルの既存のレコードを日本語に翻訳します。次のコードブロックには、メッセージの内容が含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<xml>
	<sys_ui_message>
		<code>exampleCode</code>
		<key>User {username} has been added as {role}</key>
		<language>ja</language>
		<message> {username} が {role} として追加されました。</message>
	</sys_ui_message>
</xml>

この例では、日本語以外のセッション言語で API スクリプトを実行します。

var user = {
    name: "Fred Luddy",
    role: "maint"
}
gs.info(sn_i18n.Message.getMessageLang("exampleCode","User {username} has been added as {role}",{username: user.name, role: user.role}, "ja"));

出力には、日本語のメッセージが含まれています。

Fred Luddy が maint として追加されました

次の例では、動的コンテンツに名前付きパラメーター (${username}, ${role}) を使用し、ISO 言語コード ("fr"、"ja"、"es") を使用してターゲット言語を指定し、翻訳が見つからない場合はデフォルトのメッセージにフォールバックするようにしています。

フランス語の通知:

var user = {
  name: "Fred Luddy",
  role: "maint"
};

var message = sn_i18n.Message.getMessageLang(
  "user.added",
  "User ${username} has been added as ${role}",
  { username: user.name, role: user.role },
  "fr" // French
);

gs.info(message); // Output: "L'utilisateur Fred Luddy a été ajouté en tant que maint" (if translation exists)

日本語の通知:

var user = {
  name: "Hanako Yamada",
  role: "admin"
};

var message = sn_i18n.Message.getMessageLang(
  "user.added",
  "User ${username} has been added as ${role}",
  { username: user.name, role: user.role },
  "ja" // Japanese
);

gs.info(message); // Output: "ユーザー Hanako Yamada が admin として追加されました" (if translation exists)

スペイン語の通知:

var user = {
  name: "Carlos Ruiz",
  role: "editor"
};

var message = sn_i18n.Message.getMessageLang(
  "user.added",
  "User ${username} has been added as ${role}",
  { username: user.name, role: user.role },
  "es" // Spanish
);

gs.info(message); // Output: "El usuario Carlos Ruiz ha sido añadido como editor" (if translation exists)