0Pricing
TypeScript Academy · 강의

번역 키에 타입 지정하기

메시지 파일에서 유효한 키의 유니언을 도출합니다.

번역 키에 타입 지정하기은(는) CoddyKit의 무료 TypeScript Academy 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 TypeScript Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

유효한 번역 키 도출하기

타입 안전 i18n 설정에서는 유효한 번역 키 집합이 messages 객체에서 도출됩니다. t("greetng")와 같은 오타는 실행 중 누락된 문자열 오류가 아니라 컴파일 오류가 됩니다.

messages 객체

먼저 평범한 메시지 객체를 만듭니다. 이 객체는 값과 키 타입 모두에 대한 단일 진실 공급원입니다.

const messages = {
  greeting: "Hello",
  farewell: "Goodbye",
  cart: {
    empty: "Your cart is empty",
    checkout: "Proceed to checkout",
  },
} as const;

keyof를 사용한 최상위 키

평면 객체에서는 keyof typeof로 키의 유니온을 얻을 수 있습니다.

type TopKeys = keyof typeof messages;
// "greeting" | "farewell" | "cart"

중첩 구조의 문제

실제 메시지 카탈로그는 중첩되어 있습니다. 최상위 키뿐 아니라 "cart.empty"와 같은 점 표기 경로가 필요합니다. 객체를 순회하는 재귀 타입이 필요합니다.

재귀 경로 타입

조건부 타입과 매핑된 타입을 함께 사용하면 중첩 객체를 재귀적으로 탐색하고 키에 접두사를 붙여 점 표기 경로를 만들 수 있습니다. 접두사에는 템플릿 리터럴 타입이 사용되며, 실제 코드에서는 백틱으로 작성한 [backtick]${K}.${Paths<T[K]>}[backtick] 형태입니다. 목록을 간결하게 유지하기 위해 여기서는 이를 JoinPath(K, child)로 표시합니다.

type JoinPath<K extends string, Rest extends string> = K + "." + Rest;
// (Real TS uses a template literal type:
//   the K dot Rest pattern delimited by backticks.)

type Paths<T> = {
  [K in keyof T & string]: T[K] extends string
    ? K
    : K | (T[K] extends object
        ? JoinPath<K, Paths<T[K]>>
        : never);
}[keyof T & string];

적용하기

messages 타입을 Paths에 전달하면 유효한 모든 점 표기 키를 얻을 수 있습니다.

type MsgKey = Paths<typeof messages>;
// "greeting" | "farewell" | "cart" | "cart.empty" | "cart.checkout"

리프 전용 키

중간 객체를 제외하고 리프 경로(실제 문자열)만 필요한 경우가 많습니다. 문자열이 아닌 노드를 건너뛰도록 재귀를 조정하세요. K-점-자식 접두사에도 템플릿 리터럴 타입이 사용되며(실제 코드에서는 백틱으로 둘러쌉니다), 여기서는 JoinPath로 표시합니다.

type LeafPaths<T> = T extends string
  ? ""
  : {
      [K in keyof T & string]: T[K] extends string
        ? K
        : JoinPath<K, LeafPaths<T[K]>>;
    }[keyof T & string];
// "greeting" | "farewell" | "cart.empty" | "cart.checkout"

타입이 지정된 t 함수

파생된 키 유니온으로 번역 함수 매개변수를 제한하면 유효한 키만 컴파일되도록 할 수 있습니다.

declare function t(key: LeafPaths<typeof messages>): string;

t("cart.empty");   // ok
t("cart.missing"); // Error: not a valid key

값 타입 확인하기

한 단계 더 나아가면 경로에 해당하는 값의 타입을 추론할 수 있으며, 이는 메시지에 문자열이 아닌 항목이 있을 때 유용합니다. 경로 인덱싱 조건부 타입은 점을 따라 이동합니다. 이 타입은 템플릿 리터럴 패턴으로 경로를 나누며, 실제 코드에서는 백틱을 사용해 infer가 포함된 Head 점 Rest 형태로 작성합니다. 아래에서는 이 분할을 SplitHead/SplitRest로 나타냅니다.

// Conceptually: split "cart.empty" into Head="cart", Rest="empty"
// using a template literal pattern with infer.

type ValueAt<T, P extends string> =
  P extends SplitHead<infer Head, infer Rest>
    ? Head extends keyof T ? ValueAt<T[Head], Rest> : never
    : P extends keyof T ? T[P] : never;

as const가 중요한 이유

as const가 없으면 문자열 값이 string으로 확장되어 이후에 필요한 리터럴 정보를 잃게 됩니다(예: 자리 표시자 추출). 카탈로그는 항상 상수로 선언하세요.

이것이 중요한 이유

카탈로그에서 키를 도출하면 메시지를 추가하거나 이름을 바꾸거나 제거할 때 허용되는 키 타입이 모든 곳에서 즉시 업데이트됩니다. 유지 관리해야 할 중앙 열거형도 없고, 오래된 문자열 상수도 남지 않습니다.

빠른 확인

번역 키 타입 지정을 제대로 이해했는지 확인해 보세요.

복습

keyof와 재귀 템플릿 리터럴 경로 타입을 사용하여 messages 객체에서 유효한 키의 유니온을 도출했습니다. 리프 전용 변형은 중간 객체를 제외하고, 타입이 지정된 t는 유효하지 않은 키를 거부하며, as const는 타입 시스템에 필요한 리터럴 정보를 보존합니다.

자주 묻는 질문

“번역 키에 타입 지정하기” 강의는 무료인가요?

네 — “번역 키에 타입 지정하기” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 TypeScript Academy 강의 전체를 잠금 해제할 수 있습니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“번역 키에 타입 지정하기”에서 뭘 배우나요?

메시지 파일에서 유효한 키의 유니언을 도출합니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

TypeScript Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 TypeScript Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“번역 키에 타입 지정하기” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 TypeScript Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 TypeScript Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. 번역 키에 타입 지정하기
  2. 보간 타입 안전성
  3. 타입을 활용한 복수형 처리
  4. 로케일 인식 타입 추론
← TypeScript Academy(으)로 돌아가기