다국어 지원? CAP _texts 테이블이 다 해줍니다 #shorts #SAP #CAP

CAP Localized Data란

CAP for Node는 다국어 데이터를 손쉽게 처리하기 위해 localized 키워드와 @cds.localized 어노테이션을 제공합니다. 엔티티 필드에 localized를 붙이면 CAP 런타임이 자동으로 보조 텍스트 테이블을 생성하고, OData 요청 시 Accept-Language 헤더에 따라 적절한 번역본을 반환합니다. 개발자가 별도의 JOIN 쿼리나 locale 분기 로직을 작성하지 않아도 i18n이 자연스럽게 처리됩니다.

CDS 선언 — localized 키워드

다국어로 표시되어야 하는 필드에 localized를 붙입니다. 일반적으로 상품명, 설명, 카테고리명 등 사용자에게 노출되는 텍스트가 후보입니다. 가격이나 식별자처럼 언어와 무관한 값은 그대로 둡니다.

entity Products : cuid {
  name        : localized String(100);
  description : localized String(500);
  price       : Decimal(10,2);
}

_texts 테이블 자동 생성

위 CDS를 컴파일하면 CAP는 원본 Products 테이블 외에 Products_texts 보조 테이블을 자동으로 만듭니다. 이 테이블은 locale과 원본 키로 식별되며, localized로 선언된 필드만 포함합니다.

Products_texts {
  locale      : String(5);  -- 'en', 'ko', 'de' ...
  ID          : UUID;
  name        : String(100);
  description : String(500);
}

원본 Products 테이블에는 기본 언어 값이 저장되고, 다른 언어 번역본은 Products_texts에 누적됩니다.

쿼리 자동 언어 필터링

클라이언트가 OData 요청 시 Accept-Language 헤더를 지정하면 CAP가 자동으로 해당 locale에 맞는 텍스트로 응답합니다. 매칭되는 번역이 없으면 기본 언어로 폴백합니다.

// Accept-Language: ko → name: "노트북"
await fetch('/odata/v4/catalog/Products', {
  headers: { 'Accept-Language': 'ko' }
});

// Accept-Language: en → name: "Laptop"
await fetch('/odata/v4/catalog/Products', {
  headers: { 'Accept-Language': 'en' }
});

번역 데이터 입력

초기 번역 데이터는 CSV 시드 파일로 주입하는 방식을 권장합니다. db/data/ 폴더에 <namespace>-Products_texts.csv 형식으로 두면 cds deploy 시 함께 적재됩니다.

// 런타임 추가 (Node.js 핸들러)
const { Products_texts } = cds.entities('my.shop');
await INSERT.into(Products_texts).entries({
  locale: 'ja', ID: productId,
  name: 'ノートパソコン'
});

핵심 한 줄

localized 키워드 한 번이면 CAP가 _texts 테이블, 자동 JOIN, Accept-Language 폴백까지 처리해 다국어 OData 서비스를 빠르게 구성할 수 있습니다.