메시지 - 전역

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 08월 07일
  • 소요 시간: 11분

    • Message Server API를 사용하면 code 매개 변수와 동일한 코드, message 매개 변수와 동일한 key 및 세션 언어(또는 대체 언어)와 동일한 언어를 가진 항목에 대해 Message [sys_ui_message] 테이블에서 지역화된 메시지를 검색할 수 있습니다.

    메시지 API는 사용자의 세션 언어 또는 지정된 언어 매개변수를 기반으로 메시지를 동적으로 가져오는 국제화(i18n)를 지원합니다. 이 API는 다음과 같은 세 가지 주요 기능을 제공합니다.
    • 명확성: 코드와메시지의 복합 키를 사용하여 서로 다른 컨텍스트에서 사용되는 동일한 문자열을 구분합니다(예: 동사 대 명사로 "open").
    • 명명된 매개변수: 명명된 자리 표시자를 사용하여 메시지 템플릿으로 값을 동적으로 보간할 수 있습니다.
    • 언어 제어: getMessageLang 을 사용하면 메일 병합 또는 다국어 알림 2 3과 같은 시나리오에 유용한 대상 언어를 지정할 수 있습니다.

    메시지 API는 sn_i18n 네임스페이스 내의 표준 기본 시스템과 함께 제공되며 액세스하는 데 플러그인이나 특별한 역할이 필요하지 않습니다. 이 클래스 내에서 메서드를 호출하기 전에 적절한 메시지 [sys_ui_message] 기록이 있고 일치하는 키 및 코드 필드로 채워져 있는지 확인하십시오.

    Message.getMessage(문자열 코드, 문자열 메시지, 맵 인수)

    명확성 및 동적 컨텐츠 삽입을 허용하면서 메시지 [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] 테이블의 키 필드에 해당합니다.
    args JSON 옵션입니다. 메시지에 값을 동적으로 삽입하는 데 사용되는 명명된 매개변수의 맵입니다. 키는 메시지의 명명된 매개변수와 일치합니다. 값은 범위 내에 있는 문자열 리터럴 또는 변수/상수일 수 있습니다.

    예를 들어 메시지가 "Hello, ${John}!"인 경우 {name: "John"}을 전달하여 "Hello, John!"을 렌더링할 수 있습니다.
    표 2. 반환
    유형 설명
    문자열
    다음과 같은 경우 메시지 [sys_ui_message] 테이블에서 값을 반환합니다.
    • 메시지 매개변수의 처음 255자는 키 필드와 일치합니다.
    • 코드 매개변수의 처음 255자는 코드 필드와 일치합니다.
    • 언어 필드(또는 언어 필드가 지정되지 않은 경우 세션 언어)는 언어 필드와 일치합니다.

    일치하는 항목이 없으면 대체 언어가 일치하는지 확인합니다( 참조 Set a fallback language). 일치하는 항목이 여전히 발견되지 않으면 메시지 값(두 번째 매개변수)이 리턴되고 주석이 제거됩니다.

    명명된 매개변수는 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

    이 예제에서는 ("satus.open")을 사용하여 메시지를 message 명확하게 하고 번역을 찾을 수 없는 경우 ("Open")를 대체로 사용합니다 code .

    명명된 매개변수의 기본 사용법

    
/ 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)

    이 예제에서는 ("greeting.personal")을 사용하여 code 이 인사말을 다른 인사말과 구별하고 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] 테이블의 키 필드에 해당합니다.
    args JSON 옵션입니다. 메시지에 값을 동적으로 삽입하는 데 사용되는 명명된 매개변수의 맵입니다. 키는 메시지의 명명된 매개변수와 일치합니다. 값은 범위 내에 있는 문자열 리터럴 또는 변수/상수일 수 있습니다.

    예를 들어 메시지가 "Hello, ${John}!"인 경우 {name: "John"}을 전달하여 "Hello, John!"을 렌더링할 수 있습니다.
    언어 문자열 옵션입니다. 메시지를 반환할 언어입니다.

    형식: BCP-47 언어 코드

    기본값: 세션 언어
    표 4. 반환
    유형 설명
    문자열
    다음과 같은 경우 메시지 [sys_ui_message] 테이블에서 값을 반환합니다.
    • 메시지 매개변수의 처음 255자는 키 필드와 일치합니다.
    • 코드 매개변수의 처음 255자는 코드 필드와 일치합니다.
    • 언어 필드(또는 언어 필드가 지정되지 않은 경우 세션 언어)는 언어 필드와 일치합니다.

    일치하는 항목이 없으면 대체 언어가 일치하는지 확인합니다( 참조 Set a fallback language). 일치하는 항목이 여전히 발견되지 않으면 메시지 값(두 번째 매개변수)이 리턴되고 주석이 제거됩니다.

    명명된 매개변수는 args 매개변수에 전달된 맵의 지정된 값으로 대체됩니다.

    다음 예제에서는 getMessageLang() 메서드를 호출하여 Message [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)