번역 파일 구조

22.2.1. 파일 구조

번역 파일은 언어별, 네임스페이스별로 분리하여 관리해야 합니다.

src/locales/
├── ko/                  # 한국어
│   ├── common.json
│   ├── pages.json
│   ├── components.json
│   └── validation.json
├── en/                  # 영어
│   └── (동일 구조)
└── ja/                  # 일본어
    └── (동일 구조)

• 번역 파일은 src/locales/{lang}/{namespace}.json 경로에 위치해야 합니다.
• 각 언어 디렉토리는 동일한 네임스페이스 파일 구조를 유지해야 합니다.
• 단일 파일에 모든 번역을 넣지 않고, 네임스페이스별로 분리하여 유지보수성을 확보해야 합니다.
• JSON 포맷을 사용해야 합니다. YAML 등 다른 포맷은 허용되지 않습니다.

---

22.2.2. 키 네이밍 규칙

번역 키는 일관된 네이밍 규칙을 따라야 합니다.

규칙	설명	예시
도트 표기법	계층 구조를 도트로 구분	pages.user.title
camelCase	개별 단어 구분	errorMessage, submitButton
의미 기반	UI 위치가 아닌 의미 기준으로 작명	validation.required

{
  "pages": {
    "user": {
      "title": "사용자 관리",
      "empty": "등록된 사용자가 없습니다."
    },
    "dashboard": {
      "title": "대시보드",
      "welcome": "환영합니다, {name}님."
    }
  }
}

• 키 이름은 camelCase를 사용해야 합니다. snake_case 또는 kebab-case는 사용하지 않습니다.
• 키 이름은 해당 텍스트의 의미를 반영해야 합니다. UI 위치(leftSidebarTitle)를 기준으로 작명하지 않습니다.
• 동적 값은 중괄호({name})를 사용한 보간 문법으로 처리합니다.
• 키 깊이는 최대 4단계까지 허용합니다. 그 이상 중첩이 필요한 경우 네임스페이스를 분리해야 합니다.

---

22.2.3. 네임스페이스

다음 표준 네임스페이스를 사용하여 번역 키를 분류해야 합니다.

네임스페이스	용도	예시
common	공통 UI 요소 (버튼, 라벨, 상태)	common.save, common.cancel
pages	페이지별 고유 텍스트	pages.login.title
components	공용 컴포넌트 내부 텍스트	components.modal.close
validation	폼 유효성 검사 메시지	validation.required
error	오류 메시지	error.notFound, error.serverError

• 여러 페이지에서 공통으로 사용하는 텍스트는 반드시 common 네임스페이스에 정의해야 합니다.
• 특정 페이지에서만 사용하는 텍스트는 pages 네임스페이스에 정의합니다.
• 프로젝트 규모에 따라 네임스페이스를 추가할 수 있으나, 표준 네임스페이스의 용도를 변경하지 않아야 합니다.

---

22.2.4. 복수형 처리

복수형이 필요한 텍스트는 vue-i18n의 복수형 문법을 사용하여 처리해야 합니다.

{
  "items": "항목 없음 | {count}개 항목 | {count}개 항목"
}

<template>
  <p>{{ $t('items', { count: itemCount }, itemCount) }}</p>
</template>

• 복수형 구분은 파이프(|)로 구분합니다. 순서는 없음 | 단수 | 복수입니다.
• 한국어는 복수형 구분이 없으므로 단수와 복수를 동일하게 작성합니다.
• 영어 번역 파일에서는 단수({count} item)와 복수({count} items)를 구분하여 작성해야 합니다.
• 숫자 0에 대한 별도 표현이 필요한 경우 세 가지 형태를 모두 정의합니다.
• 복수형 규칙이 복잡한 언어(아랍어 등)를 추가 지원할 경우, vue-i18n의 pluralRules 옵션을 설정해야 합니다.