메시지와 컨텍스트

원문 메시지를 온전히 작성하고 의미를 설명하세요. 메시지의 식별 정보는 유지하면서 달라지는 값을 삽입하세요.

문구에 담긴 동작이나 의미를 번역에서도 유지하려면 충분한 정보가 필요합니다. 원문을 온전히 작성하고 context에 용도를 설명하세요. 이름, 개수 등 달라지는 데이터는 values로 전달하세요.

tsx
import { useLingo } from "@lingo.dev/react";

export function Greeting({ name }: { name: string }) {
  const l = useLingo();
  return (
    <h1>
      {l.text("Welcome back, {name}.", {
        context: "Greeting at the top of the account dashboard",
        values: { name },
      })}
    </h1>
  );
}

결과는 문자열입니다. TextOptions에는 context: string가 필수이며, values?: Record<string, string | number>도 전달할 수 있습니다. 카탈로그에는 문장 템플릿이 저장되며, 번역문에서는 문법에 맞게 {name}의 위치를 옮길 수 있습니다.

모호한 메시지의 의미 설명하기 #

“저장”은 양식 제출을 뜻할 수도, 글을 북마크하는 동작을 뜻할 수도 있습니다. 영어 원문이 같더라도 컨텍스트에 따라 서로 다른 메시지로 구분됩니다.

ts
import { computeKey } from "@lingo.dev/react";

const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");

두 메시지는 키가 다르므로 번역자는 각 동작에 맞는 동사를 선택할 수 있습니다. “사용자에게 표시되는 텍스트” 같은 컨텍스트만으로는 이런 모호함을 해소할 수 없습니다. 표현에 영향을 줄 수 있는 동작, 대상 독자, 제약 조건을 설명하세요.

추출기는 이 정보를 카탈로그의 @context 주석에 기록합니다. 이 정보는 번역 지침이며, 화면에 표시되는 텍스트가 아닙니다. 반복해서 쓰는 용어와 지침, 문체 요구 사항은 로컬라이제이션 엔진의 번역 컨텍스트에 작성하고, 개별 메시지의 의미는 해당 호출에 함께 명시하세요.

메시지 식별 정보 #

computeKey(source: string, context?: string): string는 원문과 컨텍스트를 바탕으로 여덟 글자 길이의 키를 생성합니다. 비어 있지 않은 컨텍스트를 널 구분자로 원문과 연결하고, 결합된 입력을 유니코드 NFC 형식으로 정규화한 다음 UTF-8 바이트의 해시를 계산합니다.

유니코드에서 정규적으로 동등한 표기는 같은 키를 공유합니다. 문구, 문장 부호, 대소문자, 공백, 컨텍스트를 수정하면 새 키가 생성될 수 있습니다. 값은 해시 계산에 포함되지 않으므로 인사말에 어떤 이름을 넣어도 같은 메시지 항목을 사용합니다.

원문이나 컨텍스트를 변경한 뒤에는 다시 추출하고, 새 항목과 더 이상 참조되지 않는 항목을 확인하세요. 의미를 확인하지 않은 채 새 키에 번역을 복사하면 원문을 변경해 바꾸려던 표현이 그대로 남을 수 있습니다. 가능한 해시값의 수는 유한하며, 추출기는 수집한 메시지 간의 해시 충돌을 감지합니다.

추출 가능한 형태로 호출 작성하기 #

l.text(...) 같은 호출에서는 원문 문자열과 컨텍스트를 리터럴로 작성하세요. 런타임은 계산된 문자열을 받을 수 있지만, 추출기는 프로그램이 생성할 수 있는 모든 문자열을 추론할 수 없습니다. 호출 대상은 l 또는 useLingo이나 createLingo로 생성한 지원되는 변수여야 합니다. 인식 가능한 형식은 추출 레퍼런스에서 확인할 수 있습니다.

"Welcome, " + name 같은 원문 문자열을 생성하지 말고, 달라지는 데이터에는 플레이스홀더를 사용하세요. 고정된 템플릿은 추출하여 의미별로 한 번만 번역한 뒤 각 값에 재사용할 수 있습니다.

보간과 ICU #

단순 플레이스홀더에는 {name} 같은 이름을 사용합니다. 전달한 값은 텍스트로 변환됩니다. 단순 플레이스홀더에 해당하는 값이 없으면 플레이스홀더가 그대로 표시됩니다. values 객체를 생략하면 선택된 템플릿을 보간 없이 반환합니다.

수량이나 범주에 따라 문법이 달라지는 경우, 텍스트 포매터에서 intl-messageformat를 통해 복합 ICU 패턴을 사용할 수 있습니다.

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
  context: "Number of files attached to a message",
  values: { count: 0 },
});

이 호출은 No files를 반환합니다. 명시적인 =0 분기는 0을 해당 로캘의 일반적인 복수형 범주와 구분합니다. 선택된 템플릿에 필요한 인수를 모두 전달하세요. 복합 ICU 구문 분석이나 서식 지정에 실패하면 런타임은 해당 템플릿을 반환하고 개발 오류를 중복 없이 보고합니다. 형식이 잘못된 번역을 원문에 새로 서식을 적용한 결과로 대체하지는 않습니다.

복수형과 선택형에서는 완전한 대체 문구를 작성할 수 있는 도우미를 제공합니다. 서식 있는 텍스트에서는 이름이 지정된 태그를 처리하는 별도의 파서로 리액트 요소를 삽입합니다. 서식 있는 템플릿에 복합 ICU 표현식을 섞지 말고 용도에 맞는 형식을 사용하세요.