1011 lines
30 KiB
Markdown
1011 lines
30 KiB
Markdown
# 데이터 바인딩 - 다국어 처리
|
|
|
|
> **버전**: engine-v1.3.0+
|
|
> **관련 문서**: [data-binding.md](data-binding.md) | [g7core-api.md](g7core-api.md) | [layout-json.md](layout-json.md)
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [$localized() 헬퍼 함수 (engine-v1.4.0+)](#localized-헬퍼-함수-v140)
|
|
2. [다국어 처리 기본](#다국어-처리-기본)
|
|
3. [지연 번역 ($t:defer:)](#지연-번역-tdefer---반복-컨텍스트용-v130)
|
|
4. [모듈/플러그인 다국어 병합](#모듈플러그인-다국어-병합)
|
|
5. [다국어 파일 분할 ($partial)](#다국어-파일-분할-partial-v150)
|
|
6. [컴포넌트 다국어 처리](#컴포넌트-다국어-처리)
|
|
7. [JavaScript에서 G7Core.t() 사용](#javascript에서-g7coret-사용)
|
|
|
|
---
|
|
|
|
## $localized() 헬퍼 함수 (engine-v1.4.0+)
|
|
|
|
API에서 반환되는 다국어 객체(예: `{ ko: "한국어", en: "English" }`)를 현재 로케일에 맞게 자동으로 변환하는 헬퍼 함수입니다.
|
|
|
|
### 문제 상황
|
|
|
|
API에서 다국어 필드가 문자열 또는 객체로 반환될 수 있습니다:
|
|
|
|
```typescript
|
|
// 문자열인 경우
|
|
{ name: "샘플 모듈" }
|
|
|
|
// 객체인 경우
|
|
{ name: { ko: "샘플 모듈", en: "Sample Module" } }
|
|
```
|
|
|
|
기존에는 이를 처리하기 위해 복잡한 표현식이 필요했습니다:
|
|
|
|
```json
|
|
// 기존 방식 (129자)
|
|
"text": "{{typeof _global.selectedModule.name === 'string' ? _global.selectedModule.name : _global.selectedModule.name[$locale]}}"
|
|
```
|
|
|
|
### $localized() 사용법
|
|
|
|
```json
|
|
// 새 방식 (45자)
|
|
"text": "{{$localized(_global.selectedModule.name)}}"
|
|
```
|
|
|
|
### 로케일 폴백 체인
|
|
|
|
`$localized()` 함수는 다음 우선순위로 값을 반환합니다:
|
|
|
|
1. 현재 로케일 (`$locale`) 값
|
|
2. 한국어 (`ko`) 값
|
|
3. 영어 (`en`) 값
|
|
4. 객체의 첫 번째 값
|
|
5. 빈 문자열 (값이 없는 경우)
|
|
|
|
### 지원 입력 타입
|
|
|
|
| 입력 타입 | 반환 값 | 예시 |
|
|
|----------|---------|------|
|
|
| `null` / `undefined` | `''` (빈 문자열) | `$localized(null)` → `''` |
|
|
| 문자열 | 문자열 그대로 | `$localized("Hello")` → `"Hello"` |
|
|
| 다국어 객체 | 로케일에 맞는 값 | `$localized({ko: "안녕", en: "Hello"})` → `"안녕"` (ko 로케일) |
|
|
| 기타 | 문자열 변환 | `$localized(123)` → `"123"` |
|
|
|
|
### 사용 예시
|
|
|
|
**기본 사용**:
|
|
|
|
```json
|
|
{
|
|
"type": "basic",
|
|
"name": "P",
|
|
"text": "{{$localized(_global.selectedModule.name)}}"
|
|
}
|
|
```
|
|
|
|
**번역 파라미터와 함께 사용**:
|
|
|
|
```json
|
|
{
|
|
"text": "$t:admin.modules.modals.install_confirm|name={{$localized(_global.selectedModule.name)}}"
|
|
}
|
|
```
|
|
|
|
**문자열 연결**:
|
|
|
|
```json
|
|
{
|
|
"text": "{{$localized(_global.selectedModule.description) + ' (v' + _global.selectedModule.version + ')'}}"
|
|
}
|
|
```
|
|
|
|
**iteration 컨텍스트에서 사용**:
|
|
|
|
```json
|
|
{
|
|
"type": "basic",
|
|
"name": "Li",
|
|
"iteration": {
|
|
"source": "_global.selectedModule.admin_menus",
|
|
"item_var": "menu"
|
|
},
|
|
"text": "{{$localized(menu.name)}}"
|
|
}
|
|
```
|
|
|
|
**iteration + 문자열 연결**:
|
|
|
|
```json
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"iteration": {
|
|
"source": "_global.selectedModule.permissions",
|
|
"item_var": "perm"
|
|
},
|
|
"text": "{{$localized(perm.name) + ' (' + perm.identifier + ')'}}"
|
|
}
|
|
```
|
|
|
|
### Optional Chaining과 함께 사용
|
|
|
|
```json
|
|
{
|
|
"text": "{{$localized(_global.selectedModule?.name) || '-'}}"
|
|
}
|
|
```
|
|
|
|
### $localized() 사용 시 주의사항
|
|
|
|
```
|
|
✅ API에서 다국어 객체를 반환하는 필드에 사용
|
|
✅ 문자열/객체 타입이 혼재할 수 있는 필드에 사용
|
|
✅ iteration 컨텍스트 (menu, perm, role 등)에서도 정상 작동
|
|
$t: 번역 키와 혼동하지 말 것 ($t:는 프론트엔드 다국어 파일 참조)
|
|
$localized()는 API 응답의 다국어 객체 처리용
|
|
```
|
|
|
|
### $t: vs $localized() 비교
|
|
|
|
| 기능 | `$t:` | `$localized()` |
|
|
|------|-------|----------------|
|
|
| 용도 | 프론트엔드 다국어 키 번역 | API 응답 다국어 객체 처리 |
|
|
| 데이터 소스 | 템플릿 언어 파일 (ko.json, en.json) | API 응답 데이터 |
|
|
| 문법 | `$t:admin.title` | `{{$localized(data.name)}}` |
|
|
| 파라미터 | `$t:key\|param=value` | 지원 안 함 |
|
|
| 중첩 번역 | `$t:key\|param=$t:key2` (v1.25.0+) | 지원 안 함 |
|
|
|
|
---
|
|
|
|
## 다국어 처리 기본
|
|
|
|
### 기본 문법
|
|
|
|
| 문법 | 설명 | 예시 |
|
|
|------|------|------|
|
|
| `$t:key` | 다국어 키 | `$t:dashboard.title` |
|
|
| `$t:key\|param=value` | 파라미터 전달 | `$t:products.total\|count=10` |
|
|
| `$t:moduleIdentifier.key` | 모듈 다국어 키 | `$t:sirsoft-sample.admin.title` |
|
|
|
|
#### 모듈 식별자와 하이픈 파싱 규칙 (engine-v1.28.1+)
|
|
|
|
`$t:` 키에서 모듈 식별자는 **별도의 네임스페이스 분리 로직이 아닌, 번역 딕셔너리의 중첩 키 조회**로 처리됩니다.
|
|
|
|
- `TranslationEngine.getNestedValue()`가 `path.split('.')`으로 키를 분할하여 딕셔너리를 순차 탐색
|
|
- 예: `$t:sirsoft-ecommerce.admin.orders.title` → `['sirsoft-ecommerce', 'admin', 'orders', 'title']` 순서로 탐색
|
|
- 백엔드에서 모듈 언어 데이터를 병합할 때 모듈 identifier(`sirsoft-ecommerce`)를 최상위 키로 배치하므로, 첫 번째 `.` 앞까지가 자연스럽게 모듈 식별자 역할을 합니다
|
|
|
|
`DataBindingEngine.preprocessTranslationTokens()`는 `$t:` 키의 허용 문자에 하이픈(`-`)을 포함합니다:
|
|
|
|
```text
|
|
패턴: /\$t:[a-zA-Z_][a-zA-Z0-9_.\-]*/
|
|
^^ 하이픈 포함 (engine-v1.28.1에서 추가)
|
|
```
|
|
|
|
이를 통해 `$t:sirsoft-page.admin.key` 같은 하이픈 포함 모듈 키가 정상 파싱됩니다. `preprocessOptionalChaining()`에서도 `$t:` 패턴을 임시 토큰으로 보호하여, `.`이 optional chaining(`?.`)으로 변환되지 않도록 합니다.
|
|
|
|
### 예시
|
|
|
|
```json
|
|
{
|
|
"props": {
|
|
"title": "$t:dashboard.title",
|
|
"subtitle": "$t:dashboard.subtitle",
|
|
"total": "$t:products.total_count|count={{products.total}}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 파라미터 치환
|
|
|
|
```json
|
|
{
|
|
"text": "$t:products.total_count|count={{products.total}}"
|
|
}
|
|
|
|
// 다국어 파일: "총 {count}개의 상품"
|
|
// 결과: "총 15개의 상품"
|
|
```
|
|
|
|
### 파라미터 값에 중첩 $t: 사용 (engine-v1.25.0+)
|
|
|
|
파라미터 값 자체가 다른 번역 키를 참조해야 할 때, `$t:` 토큰을 파라미터 값으로 사용할 수 있습니다.
|
|
|
|
```json
|
|
{
|
|
"text": "$t:order.status_message|status=$t:enums.order_status.completed"
|
|
}
|
|
|
|
// 다국어 파일:
|
|
// order.status_message: "주문 상태가 {status}(으)로 변경됩니다."
|
|
// enums.order_status.completed: "배송완료"
|
|
// 결과: "주문 상태가 배송완료(으)로 변경됩니다."
|
|
```
|
|
|
|
#### 동작 원리
|
|
|
|
엔진이 2단계로 처리합니다:
|
|
|
|
1. **사전 해석**: `=$t:key` 패턴을 먼저 찾아 번역 값으로 치환
|
|
2. **메인 해석**: 일반 `$t:key|param=value` 패턴을 처리
|
|
|
|
#### 다중 파라미터 혼합
|
|
|
|
`$t:` 중첩 파라미터와 일반 파라미터를 함께 사용할 수 있습니다:
|
|
|
|
```json
|
|
{
|
|
"text": "$t:coupon.status_change|count={{selectedItems.length}}|status=$t:enums.coupon_status.stopped"
|
|
}
|
|
```
|
|
|
|
#### 주의사항
|
|
|
|
```
|
|
✅ 파라미터 값 위치에만 사용 가능 (|param=$t:key)
|
|
✅ 다중 깊이 중첩 지원 (최대 5단계, 변화 없을 때까지 반복)
|
|
✅ =$t: 패턴이 없으면 사전 해석 자체를 skip (기존 동작 무영향)
|
|
중첩 $t: 키에는 파라미터 전달 불가 ($t:key만 가능, $t:key|p=v는 불가)
|
|
```
|
|
|
|
---
|
|
|
|
## 지연 번역 ($t:defer:) - 반복 컨텍스트용 (engine-v1.3.0+)
|
|
|
|
CardGrid, DataGrid 등 **반복 렌더링 컴포넌트**의 `cellChildren` 내부에서 `row`, `item` 같은 iteration 변수를 번역 파라미터로 사용할 때는 `$t:defer:` prefix를 사용합니다.
|
|
|
|
```
|
|
중요: DynamicRenderer는 props 처리 시점에 번역을 수행하는데,
|
|
이 시점에는 row 컨텍스트가 없어서 {{row.xxx}}가 빈 문자열이 됨
|
|
✅ 해결: $t:defer: prefix를 사용하면 번역이 renderItemChildren으로 지연됨
|
|
```
|
|
|
|
### 문법
|
|
|
|
| 문법 | 설명 | 처리 시점 |
|
|
|------|------|----------|
|
|
| `$t:key` | 일반 번역 | DynamicRenderer (즉시) |
|
|
| `$t:defer:key` | 지연 번역 | renderItemChildren (iteration 컨텍스트 포함) |
|
|
|
|
### 사용 예시
|
|
|
|
```json
|
|
{
|
|
"name": "CardGrid",
|
|
"props": {
|
|
"cellChildren": [
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"text": "$t:defer:admin.modules.vendor|vendor={{row.vendor}}"
|
|
},
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"if": "{{row.dependencies && row.dependencies.length > 0}}",
|
|
"text": "$t:defer:admin.modules.dependencies|deps={{row.dependencies.join(', ')}}"
|
|
},
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"if": "{{!row.dependencies || row.dependencies.length === 0}}",
|
|
"text": "$t:admin.modules.no_dependencies"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 동작 원리
|
|
|
|
1. `DynamicRenderer.resolveTranslationsDeep`이 `$t:defer:` prefix를 감지하면 번역을 건너뜀
|
|
2. 원본 문자열이 그대로 `cellChildren` prop으로 전달됨
|
|
3. `renderItemChildren`이 각 row를 렌더링할 때 `$t:defer:` 번역 수행
|
|
4. 이 시점에는 `row` 컨텍스트가 있어서 `{{row.vendor}}`가 올바르게 해석됨
|
|
|
|
### 사용 시나리오
|
|
|
|
| 시나리오 | 사용 문법 |
|
|
|----------|----------|
|
|
| 일반 페이지 제목, 버튼 텍스트 | `$t:key` |
|
|
| CardGrid/DataGrid의 cellChildren에서 row 데이터 참조 | `$t:defer:key` |
|
|
| 리스트 아이템에서 item 데이터 참조 | `$t:defer:key` |
|
|
|
|
### 주의사항
|
|
|
|
```
|
|
✅ row., item., product. 등 iteration 변수 참조 시 $t:defer: 사용
|
|
✅ 일반 전역 데이터 참조 시에는 $t: 사용 (불필요한 defer 사용 금지)
|
|
$t:defer:는 renderItemChildren 내부에서만 처리됨
|
|
일반 컴포넌트에서 $t:defer: 사용 시 번역되지 않음
|
|
```
|
|
|
|
---
|
|
|
|
## 모듈/플러그인 다국어 병합
|
|
|
|
```
|
|
중요: 모듈과 플러그인도 템플릿과 동일한 다국어 시스템 사용
|
|
✅ 필수: moduleIdentifier를 키로 사용한 네이밍 규칙 준수
|
|
```
|
|
|
|
### 핵심 원칙
|
|
|
|
1. **템플릿 언어 JSON 서빙 시 자동 병합**: 활성화된 모듈과 플러그인의 다국어 데이터가 템플릿 언어 데이터와 병합되어 프론트엔드에 전달됩니다.
|
|
2. **moduleIdentifier 키 네이밍**: 병합된 JSON에서 각 모듈/플러그인의 언어 데이터는 해당 확장의 identifier를 최상위 키로 사용합니다.
|
|
3. **내부 파일에는 identifier 없음**: 모듈/플러그인 내부의 언어 파일(`resources/lang/*.json`)에는 moduleIdentifier가 포함되지 않습니다.
|
|
|
|
### 모듈 내부 언어 파일 구조
|
|
|
|
```json
|
|
// modules/sirsoft-sample/resources/lang/ko.json
|
|
{
|
|
"admin": {
|
|
"index": {
|
|
"title": "샘플 항목 관리",
|
|
"description": "샘플 모듈의 항목을 관리합니다"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 병합된 언어 JSON 구조 (프론트엔드로 전달)
|
|
|
|
```json
|
|
{
|
|
"auth": {
|
|
"login": "로그인",
|
|
"logout": "로그아웃"
|
|
},
|
|
"sirsoft-sample": {
|
|
"admin": {
|
|
"index": {
|
|
"title": "샘플 항목 관리",
|
|
"description": "샘플 모듈의 항목을 관리합니다"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 레이아웃에서 모듈 다국어 사용
|
|
|
|
```json
|
|
{
|
|
"id": "page-title",
|
|
"type": "basic",
|
|
"name": "H1",
|
|
"props": {
|
|
"text": "$t:sirsoft-sample.admin.index.title"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 병합 우선순위
|
|
|
|
1. 코어 (`lang/{locale}.json` + partial) — 베이스 레이어
|
|
2. 템플릿 언어 데이터
|
|
3. 모듈 언어 데이터 (모듈 identifier를 키로 추가)
|
|
4. 플러그인 언어 데이터 (플러그인 identifier를 키로 추가)
|
|
5. 활성 언어팩 (`template.language.merge` filter 훅 — 가장 높은 우선순위)
|
|
|
|
### 병합 정책 — Deep Merge (재귀 병합)
|
|
|
|
5개 레이어는 `array_merge` 가 아닌 재귀 deep merge (`deepMergeLanguageData`) 로 합쳐진다. 동일 top-level 키 (`layout_editor`, `core`, `auth` 등) 의 하위 트리를 leaf 까지 내려가며 병합하고, 어느 한쪽이 다른 레이어의 부분 트리만 정의해도 나머지 형제 키가 보존된다.
|
|
|
|
- assoc 트리 ↔ assoc 트리 충돌 → 재귀 병합 (양쪽 leaf 모두 보존, 동일 leaf 는 뒤가 우선)
|
|
- list / scalar / 한쪽만 array → 뒤 입력으로 덮어쓰기
|
|
- 우선순위(낮음 → 높음): 코어 < 템플릿 < 모듈 < 플러그인 < 활성 언어팩
|
|
|
|
확장 작성자 영향:
|
|
|
|
- 코어 도메인 네임스페이스 안에 자신의 sub-key 만 정의해도 안전. 예: 템플릿이 `layout_editor.palette` 만 정의해도 코어의 `layout_editor.chrome / device / zoom / preview / save` 가 살아남는다
|
|
- 코어 leaf 를 의도적으로 오버라이드하려면 동일 키 경로에 leaf 만 정의 (트리 교체 의도가 아니라 leaf override 의도임을 코드로 표현)
|
|
- 모듈/플러그인은 식별자 wrap (`module.{id}.*` / `plugin.{id}.*`) 사용을 우선 — 코어 도메인과 충돌할 일이 없고 deep merge 부작용도 회피
|
|
|
|
배경: 과거 shallow `array_merge` 는 동일 top-level 키 시 트리 전체가 교체되어, 템플릿이 한 sub-key 만 정의해도 코어의 다른 sub-key 가 통째 누락되는 결함이 발생. 상세 정책 / 회귀 사례는 [docs/extension/language-packs.md](../extension/language-packs.md#병합-정책--deep-merge-재귀-병합) 참조.
|
|
|
|
### 백엔드 구현 (`TemplateService`)
|
|
|
|
```php
|
|
public function getLanguageDataWithModules(string $identifier, string $locale): array
|
|
{
|
|
// 1. 템플릿 언어 데이터 로드
|
|
$templateLangData = $this->getLanguageData($identifier, $locale);
|
|
|
|
// 2. 활성 모듈 언어 데이터 로드 및 병합
|
|
$moduleLangData = $this->loadActiveModulesLanguageData($locale);
|
|
|
|
// 3. 활성 플러그인 언어 데이터 로드 및 병합
|
|
$pluginLangData = $this->loadActivePluginsLanguageData($locale);
|
|
|
|
// 4. 코어 자체의 프론트엔드 다국어 자원 로드 (베이스 레이어)
|
|
$coreLangData = $this->loadCoreFrontendLanguageData($locale);
|
|
|
|
// 5. Deep merge — assoc 트리 재귀 병합, list/scalar leaf 는 뒤가 우선
|
|
// 우선순위(낮음 → 높음): 코어 < 템플릿 < 모듈 < 플러그인
|
|
$mergedData = $this->deepMergeLanguageData(
|
|
$coreLangData, $templateLangData, $moduleLangData, $pluginLangData
|
|
);
|
|
|
|
// 6. 활성 언어팩 filter 훅 (가장 높은 우선순위 — 코어/모듈/플러그인 모두 덮어쓸 수 있음)
|
|
$mergedData = HookManager::applyFilters('template.language.merge', $mergedData, $identifier, $locale);
|
|
|
|
return ['success' => true, 'data' => $mergedData, 'error' => null];
|
|
}
|
|
|
|
private function loadActiveModulesLanguageData(string $locale): array
|
|
{
|
|
$langData = [];
|
|
$activeModules = $this->moduleManager->getActiveModules();
|
|
|
|
foreach ($activeModules as $module) {
|
|
$moduleIdentifier = $module->getIdentifier();
|
|
$langFilePath = base_path("modules/{$moduleIdentifier}/resources/lang/{$locale}.json");
|
|
|
|
if (file_exists($langFilePath)) {
|
|
$content = file_get_contents($langFilePath);
|
|
$data = json_decode($content, true);
|
|
if (json_last_error() === JSON_ERROR_NONE && is_array($data)) {
|
|
$langData[$moduleIdentifier] = $data;
|
|
}
|
|
}
|
|
}
|
|
|
|
return $langData;
|
|
}
|
|
```
|
|
|
|
### 캐시 무효화
|
|
|
|
모듈/플러그인 활성화/비활성화 시 템플릿 언어 캐시가 자동으로 무효화됩니다:
|
|
|
|
```php
|
|
// ModuleManager, PluginManager에서 트레이트 사용
|
|
use App\Extension\Traits\ClearsTemplateCaches;
|
|
|
|
class ModuleManager implements ModuleManagerInterface
|
|
{
|
|
use ClearsTemplateCaches;
|
|
|
|
public function activateModule(string $identifier): bool
|
|
{
|
|
// 모듈 활성화 로직
|
|
// ...
|
|
|
|
// 템플릿 언어 캐시 무효화
|
|
$this->clearAllTemplateLanguageCaches();
|
|
|
|
return true;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 모듈/플러그인 개발 시 주의사항
|
|
|
|
```
|
|
✅ `resources/lang/{locale}.json` 파일에 moduleIdentifier 없이 순수 키만 작성
|
|
✅ 레이아웃 JSON에서 `$t:moduleIdentifier.key.path` 형태로 참조
|
|
❌ 내부 파일에 `{ "moduleIdentifier": { ... } }` 형태로 작성 금지
|
|
```
|
|
|
|
---
|
|
|
|
## 다국어 파일 분할 ($partial) (engine-v1.5.0+)
|
|
|
|
대용량 다국어 JSON 파일을 여러 개의 작은 파일로 분할하여 관리할 수 있습니다. 레이아웃 시스템의 `partial` 패턴과 유사하게 동작합니다.
|
|
|
|
```
|
|
중요: 분할해도 API 응답은 기존과 동일 (병합된 단일 JSON)
|
|
✅ 장점: 파일 관리 용이, Git 충돌 감소, 협업 효율 향상
|
|
```
|
|
|
|
### $partial 문법
|
|
|
|
메인 다국어 파일에서 `$partial` 키를 사용하여 외부 partial 파일을 참조합니다.
|
|
**중요:** `$partial` 값에는 `partial/{locale}/`을 포함한 전체 상대 경로를 명시합니다. (레이아웃 partial과 동일한 패턴)
|
|
|
|
```json
|
|
// ko.json (메인 파일)
|
|
{
|
|
"common": {
|
|
"$partial": "partial/ko/common.json"
|
|
},
|
|
"admin": {
|
|
"$partial": "partial/ko/admin.json"
|
|
},
|
|
"errors": {
|
|
"network": "네트워크 오류"
|
|
}
|
|
}
|
|
```
|
|
|
|
```json
|
|
// en.json (메인 파일)
|
|
{
|
|
"common": {
|
|
"$partial": "partial/en/common.json"
|
|
},
|
|
"admin": {
|
|
"$partial": "partial/en/admin.json"
|
|
}
|
|
}
|
|
```
|
|
|
|
```json
|
|
// partial/ko/common.json
|
|
{
|
|
"save": "저장",
|
|
"cancel": "취소",
|
|
"delete": "삭제"
|
|
}
|
|
```
|
|
|
|
**병합 결과:**
|
|
```json
|
|
{
|
|
"common": {
|
|
"save": "저장",
|
|
"cancel": "취소",
|
|
"delete": "삭제"
|
|
},
|
|
"admin": { ... },
|
|
"errors": {
|
|
"network": "네트워크 오류"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 디렉토리 구조
|
|
|
|
Partial 파일은 `partial/{locale}/` 디렉토리에 위치합니다.
|
|
|
|
**템플릿:**
|
|
```
|
|
templates/sirsoft-admin_basic/lang/
|
|
├── ko.json # 메인 파일 ($partial 참조)
|
|
├── en.json # 메인 파일 ($partial 참조)
|
|
└── partial/
|
|
├── ko/
|
|
│ ├── common.json
|
|
│ ├── admin.json
|
|
│ ├── auth.json
|
|
│ └── errors.json
|
|
└── en/
|
|
├── common.json
|
|
├── admin.json
|
|
├── auth.json
|
|
└── errors.json
|
|
```
|
|
|
|
**모듈:**
|
|
```
|
|
modules/sirsoft-ecommerce/resources/lang/
|
|
├── ko.json
|
|
├── en.json
|
|
└── partial/
|
|
├── ko/
|
|
│ ├── common.json
|
|
│ ├── admin/
|
|
│ │ ├── products.json
|
|
│ │ ├── orders.json
|
|
│ │ └── categories.json
|
|
│ └── enums.json
|
|
└── en/
|
|
└── ...
|
|
```
|
|
|
|
### 중첩 $partial
|
|
|
|
Partial 내부에서 다른 partial을 참조할 수 있습니다 (최대 10단계).
|
|
|
|
```json
|
|
// partial/ko/admin.json
|
|
{
|
|
"products": {
|
|
"$partial": "admin/products.json"
|
|
},
|
|
"orders": {
|
|
"$partial": "admin/orders.json"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 분할 기준 가이드
|
|
|
|
| 파일 크기 | 권장 분할 | 비고 |
|
|
|----------|----------|------|
|
|
| ~100줄 | 불필요 | 단일 파일 유지 |
|
|
| 100~500줄 | 선택 | 주요 섹션별 분할 |
|
|
| 500~1000줄 | 권장 | 최상위 키별 분할 |
|
|
| 1000줄+ | 필수 | 세부 섹션까지 분할 |
|
|
|
|
### 오류 처리
|
|
|
|
| 상황 | 발생 오류 |
|
|
|------|----------|
|
|
| Partial 파일 없음 | `RuntimeException: 다국어 fragment 파일을 찾을 수 없습니다` |
|
|
| JSON 파싱 오류 | `RuntimeException: 다국어 fragment JSON 파싱 오류` |
|
|
| 순환 참조 | `RuntimeException: 다국어 fragment 순환 참조 감지` |
|
|
| 최대 깊이 초과 | `RuntimeException: 다국어 fragment 최대 깊이(10) 초과` |
|
|
|
|
### 주의사항
|
|
|
|
```
|
|
✅ Partial 경로는 lang 디렉토리 기준 전체 상대 경로 (partial/{locale}/... 형식)
|
|
✅ 파일명에 .json 확장자 포함 필수
|
|
✅ 중첩 partial도 동일한 규칙 적용
|
|
순환 참조 주의 (A→B→A 형태 금지)
|
|
최대 중첩 깊이 10단계 제한
|
|
```
|
|
|
|
### 백엔드 구현
|
|
|
|
`ResolvesLanguageFragments` trait이 partial 해석을 담당합니다.
|
|
|
|
```php
|
|
// app/Extension/Traits/ResolvesLanguageFragments.php
|
|
trait ResolvesLanguageFragments
|
|
{
|
|
protected function resolveLanguageFragments(array $data, string $basePath, int $depth = 0): array
|
|
{
|
|
// $partial 디렉티브 재귀적 해석
|
|
// 순환 참조 및 최대 깊이 검사
|
|
}
|
|
}
|
|
|
|
// app/Services/TemplateService.php
|
|
class TemplateService
|
|
{
|
|
use ResolvesLanguageFragments;
|
|
|
|
private function loadLanguageFileWithFragments(string $langPath): ?array
|
|
{
|
|
// JSON 로드 후 partial 해석
|
|
// basePath는 lang 디렉토리, $partial 값에 partial/{locale}/... 전체 경로 포함
|
|
$basePath = dirname($langPath);
|
|
return $this->resolveLanguageFragments($data, $basePath);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 컴포넌트 다국어 처리
|
|
|
|
```
|
|
중요: 컴포넌트 내부에서는 다국어 키를 직접 사용하지 않음
|
|
✅ 필수: Props 기반 다국어 패턴 사용
|
|
✅ 필수: 영어를 기본값(fallback)으로 설정
|
|
```
|
|
|
|
### 핵심 원칙
|
|
|
|
그누보드7 템플릿 시스템에서 컴포넌트는 레이아웃 JSON에서 전달받은 텍스트를 그대로 표시합니다. 다국어 변환은 템플릿 엔진이 레이아웃 JSON을 렌더링할 때 자동으로 처리합니다.
|
|
|
|
### 다국어 처리 흐름
|
|
|
|
```
|
|
1. 레이아웃 JSON에 다국어 키 정의
|
|
→ "profileText": "$t:admin.profile_settings"
|
|
|
|
2. 템플릿 엔진이 현재 로케일에 따라 다국어 파일에서 값 조회
|
|
→ 한국어: "프로필 설정"
|
|
→ 영어: "Profile Settings"
|
|
|
|
3. 변환된 텍스트를 Props로 컴포넌트에 전달
|
|
→ profileText="프로필 설정" (한국어)
|
|
→ profileText="Profile Settings" (영어)
|
|
|
|
4. 컴포넌트는 전달받은 값을 그대로 표시
|
|
→ {profileText} 렌더링
|
|
```
|
|
|
|
### 올바른 컴포넌트 작성 패턴
|
|
|
|
```tsx
|
|
// ✅ 올바른 예: Props로 텍스트 받기 (영어 기본값)
|
|
export interface UserProfileProps {
|
|
user: User;
|
|
profileText?: string; // 기본값: 영어
|
|
logoutText?: string; // 기본값: 영어
|
|
onProfileClick?: () => void;
|
|
onLogoutClick?: () => void;
|
|
}
|
|
|
|
export const UserProfile: React.FC<UserProfileProps> = ({
|
|
user,
|
|
profileText = 'Profile Settings', // ✅ 영어 기본값
|
|
logoutText = 'Logout', // ✅ 영어 기본값
|
|
onProfileClick,
|
|
onLogoutClick,
|
|
}) => {
|
|
return (
|
|
<Div>
|
|
<Button onClick={onProfileClick}>
|
|
{profileText} {/* Props로 받은 텍스트 사용 */}
|
|
</Button>
|
|
<Button onClick={onLogoutClick}>
|
|
{logoutText} {/* Props로 받은 텍스트 사용 */}
|
|
</Button>
|
|
</Div>
|
|
);
|
|
};
|
|
```
|
|
|
|
### 잘못된 패턴
|
|
|
|
```tsx
|
|
// ❌ 잘못된 예: 컴포넌트 내부에서 다국어 키 사용 (금지)
|
|
export const UserProfile: React.FC<UserProfileProps> = ({ user }) => {
|
|
return (
|
|
<Div>
|
|
{/* ❌ 컴포넌트는 다국어 시스템에 직접 접근하지 않음 */}
|
|
<Button>{t('admin.profile_settings')}</Button>
|
|
<Button>{t('admin.logout')}</Button>
|
|
</Div>
|
|
);
|
|
};
|
|
```
|
|
|
|
### 레이아웃 JSON 작성 패턴
|
|
|
|
```json
|
|
{
|
|
"id": "user_profile",
|
|
"type": "composite",
|
|
"name": "UserProfile",
|
|
"props": {
|
|
"user": "{{current_user.data}}",
|
|
"profileText": "$t:admin.profile_settings", // 다국어 키
|
|
"logoutText": "$t:admin.logout" // 다국어 키
|
|
},
|
|
"data_binding": {
|
|
"user": "current_user.data"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 다국어 파일 구조
|
|
|
|
```json
|
|
// resources/lang/ko.json
|
|
{
|
|
"admin": {
|
|
"profile_settings": "프로필 설정",
|
|
"logout": "로그아웃",
|
|
"notifications": "알림",
|
|
"no_notifications": "알림이 없습니다"
|
|
}
|
|
}
|
|
|
|
// resources/lang/en.json
|
|
{
|
|
"admin": {
|
|
"profile_settings": "Profile Settings",
|
|
"logout": "Logout",
|
|
"notifications": "Notifications",
|
|
"no_notifications": "No notifications"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 기본값 규칙
|
|
|
|
1. **영어를 기본값으로 사용**: 모든 텍스트 Props의 기본값은 영어로 작성
|
|
2. **의미 있는 기본값**: 빈 문자열이 아닌 실제 사용 가능한 텍스트 제공
|
|
3. **일관성 유지**: 동일한 의미의 텍스트는 같은 표현 사용
|
|
|
|
```tsx
|
|
// ✅ 올바른 기본값
|
|
submitButtonText = 'Sign In' // 명확한 영어 텍스트
|
|
processingText = 'Processing...' // 로딩 상태 표시
|
|
emptyText = 'No notifications' // 빈 상태 메시지
|
|
|
|
// ❌ 잘못된 기본값
|
|
submitButtonText = '' // 빈 문자열 (의미 없음)
|
|
submitButtonText = '로그인' // 한국어 (영어 사용 필수)
|
|
```
|
|
|
|
### 실제 사용 예시 (LoginForm 컴포넌트)
|
|
|
|
```tsx
|
|
export interface LoginFormProps {
|
|
emailLabel?: string;
|
|
passwordLabel?: string;
|
|
submitButtonText?: string;
|
|
processingText?: string;
|
|
emailPlaceholder?: string;
|
|
passwordPlaceholder?: string;
|
|
forgotPasswordText?: string;
|
|
forgotPasswordUrl?: string;
|
|
// ...
|
|
}
|
|
|
|
export const LoginForm: React.FC<LoginFormProps> = ({
|
|
emailLabel = 'Email', // ✅ 영어 기본값
|
|
passwordLabel = 'Password', // ✅ 영어 기본값
|
|
submitButtonText = 'Sign In', // ✅ 영어 기본값
|
|
processingText = 'Processing...', // ✅ 영어 기본값
|
|
emailPlaceholder = 'Email', // ✅ 영어 기본값
|
|
passwordPlaceholder = 'Password', // ✅ 영어 기본값
|
|
forgotPasswordText = 'Forgot your password?', // ✅ 영어 기본값
|
|
// ...
|
|
}) => {
|
|
return (
|
|
<Form>
|
|
<Label>{emailLabel}</Label>
|
|
<Input placeholder={emailPlaceholder} />
|
|
<Label>{passwordLabel}</Label>
|
|
<Input type="password" placeholder={passwordPlaceholder} />
|
|
<A>{forgotPasswordText}</A>
|
|
<Button>{submitButtonText}</Button>
|
|
</Form>
|
|
);
|
|
};
|
|
```
|
|
|
|
### 레이아웃 JSON에서 사용
|
|
|
|
```json
|
|
{
|
|
"id": "login_form",
|
|
"type": "composite",
|
|
"name": "LoginForm",
|
|
"props": {
|
|
"emailLabel": "$t:auth.login.email",
|
|
"passwordLabel": "$t:auth.login.password",
|
|
"submitButtonText": "$t:auth.login.submit",
|
|
"processingText": "$t:auth.login.processing",
|
|
"emailPlaceholder": "$t:auth.login.email_placeholder",
|
|
"passwordPlaceholder": "$t:auth.login.password_placeholder",
|
|
"forgotPasswordText": "$t:auth.login.forgot_password"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Props 기반 다국어 패턴의 장점
|
|
|
|
1. **템플릿 엔진 의존성 제거**: 컴포넌트가 템플릿 엔진의 다국어 시스템에 의존하지 않음
|
|
2. **재사용성 향상**: 다른 프로젝트나 환경에서도 사용 가능
|
|
3. **테스트 용이성**: Props로 텍스트를 직접 전달하여 테스트 간소화
|
|
4. **타입 안전성**: TypeScript로 Props 타입 정의 가능
|
|
5. **폴백 동작**: 다국어 키가 없어도 영어 기본값으로 정상 표시
|
|
|
|
### 주의사항
|
|
|
|
```
|
|
금지: useTranslation, t() 함수 등 다국어 훅/함수 사용
|
|
금지: 컴포넌트 내부에서 다국어 파일 직접 import
|
|
금지: 한국어를 기본값으로 설정
|
|
✅ 필수: 모든 사용자 표시 텍스트는 Props로 받기
|
|
✅ 필수: 영어를 기본값으로 설정
|
|
✅ 필수: Props 타입에 선택적(optional) 정의
|
|
```
|
|
|
|
### 참고 컴포넌트
|
|
|
|
- `LoginForm.tsx`: 폼 라벨 및 버튼 텍스트 다국어 처리
|
|
- `UserProfile.tsx`: 드롭다운 메뉴 텍스트 다국어 처리
|
|
- `NotificationCenter.tsx`: 알림 관련 텍스트 다국어 처리
|
|
|
|
---
|
|
|
|
## JavaScript에서 G7Core.t() 사용
|
|
|
|
컴포넌트 코드에서 프로그래밍 방식으로 번역 함수를 사용할 수 있습니다.
|
|
|
|
> 전체 API 레퍼런스: [g7core-api.md](g7core-api.md#다국어-g7corelocale-g7coret)
|
|
|
|
### 컴포넌트에서 t 함수 선언
|
|
|
|
```tsx
|
|
// 컴포넌트 파일 상단에 선언
|
|
const t = (key: string, params?: Record<string, string | number>) =>
|
|
(window as any).G7Core?.t?.(key, params) ?? key;
|
|
```
|
|
|
|
### G7Core.t() 사용 예시
|
|
|
|
```tsx
|
|
// 간단한 번역
|
|
const text = G7Core.t('common.confirm'); // '확인'
|
|
|
|
// 파라미터 치환
|
|
const message = G7Core.t('admin.users.pagination_info', {
|
|
from: 1,
|
|
to: 10,
|
|
total: 100
|
|
});
|
|
// "1-10 / 총 100건"
|
|
|
|
// 컴포넌트에서 사용
|
|
<Button>{t('common.confirm')}</Button>
|
|
<Span>{t('admin.users.count', { count: 10 })}</Span>
|
|
```
|
|
|
|
### 로케일 관리 API
|
|
|
|
```typescript
|
|
// 현재 로케일 조회
|
|
const currentLocale = G7Core.locale.current(); // 'ko'
|
|
|
|
// 지원 로케일 목록
|
|
const supportedLocales = G7Core.locale.supported(); // ['ko', 'en']
|
|
|
|
// 로케일 변경
|
|
await G7Core.locale.change('en');
|
|
```
|
|
|
|
---
|
|
|
|
## 번역 면제 바인딩 (`raw:` 접두사) (engine-v1.27.0+)
|
|
|
|
사용자 입력 데이터를 표시하는 바인딩에 `raw:` 접두사를 붙이면,
|
|
데이터에 `$t:` 패턴이 포함되어도 번역되지 않고 원본이 보존됩니다.
|
|
|
|
### 사용법
|
|
|
|
| 일반 바인딩 | 번역 면제 바인딩 |
|
|
|------------|-----------------|
|
|
| `{{post.title}}` | `{{raw:post.title}}` |
|
|
| `{{comment.content}}` | `{{raw:comment.content}}` |
|
|
| `{{product.name}}` | `{{raw:product.name}}` |
|
|
|
|
### 사용 시점
|
|
|
|
- 사용자가 직접 입력한 텍스트 (게시판 제목, 댓글, 상품명, 닉네임 등)
|
|
- 시스템 데이터 (핸들러 결과, 서버 메타데이터, 설정값 등)에는 사용 금지
|
|
- `$t:` 토큰이 의도적으로 포함된 핸들러 결과 (예: DataGrid 컬럼 헤더)에는 사용 금지
|
|
|
|
### 예시
|
|
|
|
```json
|
|
{
|
|
"type": "basic",
|
|
"name": "Span",
|
|
"props": {
|
|
"text": "{{raw:post.title}}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 파이프와 함께 사용
|
|
|
|
```json
|
|
"text": "{{raw:post.title | truncate:50}}"
|
|
```
|
|
|
|
### 복잡한 표현식
|
|
|
|
```json
|
|
"text": "{{raw:post.title ?? '제목 없음'}}"
|
|
```
|
|
|
|
### 혼합 보간
|
|
|
|
일반 번역 토큰과 raw 바인딩을 같은 문자열에서 함께 사용할 수 있습니다:
|
|
|
|
```json
|
|
"text": "{{raw:post.title}} - $t:common.by {{post.author}}"
|
|
```
|
|
|
|
이 경우 `raw:` 영역 내부의 `$t:` 패턴은 보호되고, 영역 외부의 `$t:common.by`는 정상 번역됩니다.
|
|
|
|
### 내부 동작
|
|
|
|
1. `DataBindingEngine`: `raw:` 접두사를 감지하여 제거 후 정상 평가, 결과를 Unicode Noncharacter 마커(`\uFDD0`...`\uFDD1`)로 래핑
|
|
2. `resolveTranslationsDeep`: 마커가 감지되면 번역을 건너뛰고 마커만 제거하여 원본 반환
|
|
3. 객체/배열 결과는 `wrapRawDeep`로 내부 모든 리프 문자열에 마커 부착
|
|
|
|
### 주의사항
|
|
|
|
- `raw:`는 `resolveTranslationsDeep`의 `$t:` 번역만 건너뜁니다
|
|
- 표현식 내부의 `$t()` 함수 호출에는 영향 없습니다
|
|
- 핸들러 결과(`resultTo`)에 사용하면 의도된 `$t:` 번역도 건너뛰므로 주의
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [데이터 바인딩 기본](data-binding.md) - 기본 문법, 표현식
|
|
- [g7core-api.md](g7core-api.md) - G7Core 전역 API 레퍼런스
|
|
- [layout-json.md](layout-json.md) - 레이아웃 JSON 스키마
|
|
- [data-sources.md](data-sources.md) - 데이터 소스 시스템
|
|
- [state-management.md](state-management.md) - 전역 상태 관리
|