메시지 - 전역

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 11분
  • Message Server API를 사용하면 code 매개 변수와 동일한 코드, message 매개 변수와 동일한 key 및 세션 언어(또는 대체 언어)와 동일한 언어를 가진 항목에 대해 Message [sys_ui_message] 테이블에서 지역화된 메시지를 검색할 수 있습니다.

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

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

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

    명확성 및 동적 컨텐츠 삽입을 허용하면서 메시지 [sys_ui_message] 테이블에서 현지화된 메시지를 검색합니다.

    매개변수의 args 값은 문자열의 일치하는 템플릿 리터럴에 보간됩니다.

    표 1. 매개변수
    이름 유형 설명
    코드 문자열 필수 식별자로 사용되는 최대 255자의 문자열입니다. code 텍스트는 비슷하지만 의미나 문맥이 다른 메시지를 모호하게 하는 데 사용할 수 있습니다. 권장 값은 애플리케이션 범위의 이름입니다. 추가 모호성 제거가 필요한 경우 보강될 수 있습니다.

    예를 들어 "열림"은 상태 또는 작업을 의미할 수 있으므로 매개변수는 code 사용할 의미를 명확히 하는 데 도움이 됩니다. 문자열이 같지만 대/소문자가 다른 두 메시지가 필요한 경우 스크립트는 다음과 같습니다.

    sn_i18n.Message.getMessage("scopeName-open-capitalized", "Open");
    sn_i18n.Message.getMessage("scopeName-open", "open");
    메시지 문자열 필수 영어로 된 메시지입니다. 메시지 [sys_ui_message] 테이블의 필드에 해당합니다. 이 메시지는 대상 언어에 대해 현지화된 버전을 찾을 수 없는 경우에 사용됩니다.
    args JSON 옵션입니다. 메시지에 값을 동적으로 삽입하는 데 사용되는 명명된 매개변수의 맵입니다. 키는 메시지의 명명된 매개변수와 일치합니다. 값은 범위 내에 있는 문자열 리터럴 또는 변수/상수일 수 있습니다.

    예를 들어 메시지가 "Hello, {name}!"인 경우 {name: "John"} 을 전달하여 "Hello, John!"을 렌더링할 수 있습니다.

    표 2. 반환
    유형 설명
    문자열
    다음과 같은 경우 메시지 [sys_ui_message] 테이블에서 값을 반환합니다.
    • 코드 매개변수가 코드 필드와 일치합니다.
    • 메시지 매개변수의 처음 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"을 사용하여 매개변수를 code 보강하여 메시지를 모호하게 하고, message 번역을 찾을 수 없는 경우 대체로 매개변수"Open"를 사용합니다.

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

    // Retrieves a localized message with named parameters
    var message = sn_i18n.Message.getMessage(
     "scopeName” + "_greeting_personal",
     "Hello, {name}! You have {count} new messages.",
     { name: "John", count: 5 }
    );
    gs.info(message);

    출력:

    "Hello, John! You have 5 new messages." (localized if available)

    이 예에서는 이 인사말을 다른 인 message 사말과 구별하기 위해 "greeting_personal"로 매개변수를 보강하며 code 자리 표시자가 있는 템플릿입니다. args ({name: "John", count: 5})는 자리 표시자를 채웁니다.

    메시지 - getMessageLang(문자열 코드, 문자열 메시지, 맵 인수, 문자열 언어)

    현재 사용자의 세션 언어에 관계없이 메시지 [sys_ui_message] 내에서 현지화된 메시지를 지정된 언어로 검색합니다.

    매개변수의 args 값은 문자열의 일치하는 템플릿 리터럴에 보간됩니다.

    getMessageLang()은 다음과 같은 경우에 유용합니다.
    • 세션 언어 재정의: 특정 언어로 알림, 이메일 또는 보고서를 보내는 데 유용합니다.
    • 다국어 지원: 여러 지역의 사용자에게 서비스를 제공하는 애플리케이션에 적합합니다.
    • 번역 테스트: 개발자가 사용자 설정을 전환하지 않고도 메시지가 다른 언어로 표시되는 방식을 미리 볼 수 있습니다.
    표 3. 매개변수
    이름 유형 설명
    코드 문자열 필수 식별자로 사용되는 최대 255자의 문자열입니다. code 텍스트는 비슷하지만 의미나 문맥이 다른 메시지를 모호하게 하는 데 사용할 수 있습니다. 권장 값은 애플리케이션 범위의 이름입니다. 추가 모호성 제거가 필요한 경우 보강될 수 있습니다.

    예를 들어 "열림"은 상태 또는 작업을 의미할 수 있으므로 매개변수는 code 사용할 의미를 명확히 하는 데 도움이 됩니다. 문자열이 같지만 대/소문자가 다른 두 메시지가 필요한 경우 스크립트는 다음과 같습니다.

    sn_i18n.Message.getMessage("scopeName-open-capitalized", "Open");
    sn_i18n.Message.getMessage("scopeName-open", "open");
    메시지 문자열 필수 영어로 된 메시지입니다. 메시지 [sys_ui_message] 테이블의 필드에 해당합니다. 이 메시지는 대상 언어에 대해 현지화된 버전을 찾을 수 없는 경우에 사용됩니다.
    args JSON 옵션입니다. 메시지에 값을 동적으로 삽입하는 데 사용되는 명명된 매개변수의 맵입니다. 키는 메시지의 명명된 매개변수와 일치합니다. 값은 범위 내에 있는 문자열 리터럴 또는 변수/상수일 수 있습니다.

    예를 들어 메시지가 "Hello, {name}!"인 경우 {name: "John"} 을 전달하여 "Hello, John!"을 렌더링할 수 있습니다.

    언어 문자열 필수 메시지를 반환할 언어입니다.

    형식: BCP-47 언어 코드

    기본값: 세션 언어

    표 4. 반환
    유형 설명
    문자열
    다음과 같은 경우 메시지 [sys_ui_message] 테이블에서 값을 반환합니다.
    • 코드 매개변수가 코드 필드와 일치합니다.
    • 메시지 매개변수의 처음 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)