메시지 호출 타입 검사

소스 문자열, 컨텍스트, 메시지 값을 편집 중에 검사할 수 있도록 선언을 생성하고 포함하세요.

메시지 호출이 타입스크립트에서 유효하더라도 잘못된 카탈로그 항목을 요청할 수 있습니다. 컨텍스트가 바뀌거나 플레이스홀더에 오타가 있으면 화면에 소스 텍스트나 {name}이 그대로 표시될 수 있습니다. 추출 과정에서는 확인된 소스 메시지가 애플리케이션 타입 시스템의 일부가 되도록 선언을 생성합니다.

선언 생성 및 포함 #

CLI 설치를 마친 후 다음을 실행하세요.

sh
npx lingo extract --src src --source-locale en

기본 출력 파일은 locales/en.jsonc과 lingo.d.ts입니다. 기존 패턴으로 lingo.d.ts이 포함되지 않는다면 애플리케이션의 기존 tsconfig 포함 목록에 추가하세요. 나머지 항목은 그대로 유지하세요.

json
{
  "include": ["src", "lingo.d.ts"]
}

애플리케이션에서 평소 사용하는 타입 검사를 실행하세요. 컴파일러의 프로젝트 범위 밖에 있는 선언은 어떤 호출에도 제약을 적용하지 못합니다. 추출 시 --types 또는 i18n.typesPath를 사용한다면 실제 출력 경로를 대신 포함하세요.

생성된 인터페이스의 의미 #

이 파일은 소스 문자열과 각 문자열의 옵션을 추가해 LingoMessages을 확장합니다. 생성되는 구조는 다음 예시와 같습니다.

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

예시를 직접 수정하며 관리하지 말고 이 파일을 다시 생성하세요. 이제 인사말에는 values.name과 추출된 컨텍스트가 필요합니다. Save는 기록된 두 컨텍스트 중 어느 쪽이든 허용합니다. 목록에 없는 소스는 MessageKey 제약을 충족하지 못합니다.

생성된 항목이 없으면 LingoMessages은 비어 있고 MessageKey는 모든 문자열을 허용합니다. 항목이 채워지면 MessageKey는 해당 문자열 키들의 유니온 타입이 됩니다. 런타임 동작은 바뀌지 않습니다. 이 제약은 편집 시점에 l.text과 l.rich에 적용됩니다.

소스에 맞춰 타입을 최신 상태로 유지 #

텍스트, 컨텍스트 또는 플레이스홀더를 변경한 뒤에는 다시 추출하세요. 삭제된 메시지는 고아 항목이 되어 생성 대상에서 제외됩니다. 컨텍스트가 없는 항목은 같은 소스의 다른 활성 항목이 컨텍스트를 제공하지 않는 한 시그니처 생성에 반영되지 않습니다. 같은 소스에 여러 컨텍스트가 있으면 유니온 타입을 이룹니다.

파일을 쓰지 않고 최신 상태인지 확인하려면 다음을 실행하세요.

sh
npx lingo extract --src src --source-locale en --check

이 명령은 JSONC와 선언을 모두 현재 추출 결과와 비교합니다. 번역을 요청하는 것이 아니라 로컬에서 검사하는 작업입니다. 오래된 선언이 이전 메시지 목록을 기준으로 계속 사용되는 일을 놓치지 않도록 타입 검사와 함께 실행하세요.

값 타입 및 검사 범위 #

생성기는 최상위 ICU 인수를 인식합니다. 복수형, 서수형, 숫자 인수에는 number을, 선택 인수에는 string를, 날짜 및 시간 인수에는 Date | number을, 단순 플레이스홀더에는 string | number를 사용합니다. 복수형 분기 안에 중첩된 플레이스홀더를 모두 찾아내지는 못하므로 해당 분기의 값은 명시적으로 테스트하세요.

생성된 소스 제약은 text과 rich에 적용됩니다. plural 및 select 도우미는 자체 형식 및 옵션 시그니처를 유지합니다. 리치 호출에는 선택 사항인 태그 맵이 추가되지만, 선언은 대상 번역의 태그 배치까지 검증하지는 않습니다.

타입은 호출이 추출된 소스의 규약을 충족하는지 알려줍니다. 렌더링 테스트는 불러온 번역에서 해당 값을 사용할 수 있는지 알려줍니다. 두 가지를 모두 유지하세요. 호출이 유효해도 카탈로그 항목이 없거나 대상 번역의 ICU 형식이 잘못되어 있을 수 있습니다.