국제화 (i18n)

Q-Framework는 어노테이션 기반으로 다국어 문자열을 선언합니다. 별도의 메시지 파일 관리 없이 엔티티 선언에서 바로 다국어 표시명을 정의할 수 있습니다.

문자열 선언

@QfI18n

다국어 표시명을 선언하는 기본 어노테이션입니다. 필드에 선언하면 해당 필드의 표시 레이블을 정의합니다.

@QfEntity(
    appKey = "app",
    name = @QfI18n(defaultMessage = "Product", texts = {
        @QfI18nText(locale = "ko", message = "상품"),
        @QfI18nText(locale = "ja", message = "製品")
    })
)
public class ProductEntity {

    @QfI18n(defaultMessage = "Product Name", texts = {
        @QfI18nText(locale = "ko", message = "상품명")
    })
    @QfListAttribute(sortable = true)
    @QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))
    private String name;

    @QfI18n(defaultMessage = "Price")
    @QfListAttribute(sortable = true)
    private Integer price;
}

@QfDisplayHint

필드에 대한 툴팁 또는 플레이스홀더 힌트를 선언합니다.

@QfI18n(defaultMessage = "Email")
@QfDisplayHint(text = "example@company.com 형식으로 입력하세요")
@QfCreateAttribute
private String email;

속성	설명
key	i18n 조회를 위한 메시지 리소스 키
text	리터럴 힌트 텍스트 (폴백)

---

키 규칙

컴파일 시점에 다국어 키가 자동으로 생성됩니다.

{appKey}.{entityName}.field.{fieldName}
    ↓
app.product.field.name
app.product.field.price

엔티티 표시명:

{appKey}.{entityName}.label
    ↓
app.product.label

이 키는 프론트엔드의 i18n 시스템과 자동으로 연동됩니다.

---

프론트엔드 표시 흐름

백엔드 메타데이터 API
    ↓
{
  "fields": [
    {
      "name": "name",
      "i18n": {
        "defaultMessage": "Product Name",
        "texts": [{ "locale": "ko", "message": "상품명" }]
      }
    }
  ]
}
    ↓
프론트엔드 QfEntityView 컴포넌트
    ↓
현재 언어 설정에 따라 자동으로 표시명 선택

---

언어 설정

프론트엔드에서 언어를 설정합니다.

// q-vue 설정
import { createQFramework } from '@softminds/q-vue'

const qf = createQFramework({
  locale: 'ko',           // 기본 언어
  fallbackLocale: 'en'    // 폴백 언어
})

언어가 ko로 설정되면 해당 locale의 message 값이 표시되고, 번역이 없으면 defaultMessage 값으로 폴백됩니다.

---

지원 언어

현재 지원 언어:

코드	언어
ko	한국어
en	영어
ja	일본어
zh	중국어 (간체)

INFO

언어 코드는 ISO 639-1 표준을 따릅니다. 추가 언어는 SPI를 통해 확장 가능합니다.

---

다음 단계

• 이력 관리 — 변경 이력 추적
• Excel 기능 — 대량 데이터 처리