Gnuboard7/docs/extension/language-packs.md

언어팩 시스템 (Language Packs)

TL;DR (5초 요약)

1. 코어/번들 확장의 lang/{ko,en}/ 는 가상 보호 행으로 자동 노출 (DB 없이 항상 active+protected, 수정 불가)
2. lang-packs/_bundled/ 패키지(ja, fr 등)는 비보호 — 사용자가 install/uninstall/update/activate/deactivate 자유
3. 활성화 시 의존성 + 버전 호환성 자동 검사 (호스트 확장 active + requires.target_version 제약)
4. 호스트 확장 비활성화 시 종속 언어팩 자동 비활성화. 재활성화 시 모달로 "다음 언어팩도 활성화 하시겠습니까" 질의
5. 업데이트 우선순위: GitHub 1순위 + bundled 폴백 (force 시 bundled 우선) — 모듈/플러그인 패턴 동일

개요

G7 의 언어팩 시스템은 모듈/플러그인/템플릿 시스템과 동일한 멘탈 모델을 재사용한 설치 가능한 다국어 아티팩트 입니다. lang-packs/ 디렉토리가 쓰기 가능 영역으로 분리되어 있어 코어 업데이트 시에도 언어팩이 유실되지 않습니다.

디렉토리 구조

lang-packs/
├── _bundled/                                   # Git 추적 (번들 메타데이터)
│   ├── g7-core-ko/
│   │   └── language-pack.json
│   ├── g7-core-en/
│   ├── g7-template-sirsoft-admin_basic-ko/
│   ├── g7-template-sirsoft-admin_basic-en/
│   ├── g7-template-sirsoft-basic-ko/
│   └── g7-template-sirsoft-basic-en/
├── _pending/                                   # Git 제외, 업로드 임시
└── {identifier}/                               # Git 제외, 활성 설치본
    ├── language-pack.json
    ├── backend/{locale}/*.php                  # Laravel trans 파일
    ├── frontend/*.json                         # 템플릿 다국어 fragment
    └── seed/*.json                             # 시드 다국어 데이터

코어 다국어 자원의 위치

코어 자체의 다국어 자원은 모듈/플러그인/템플릿과 동일한 lang/ 트리 구조를 사용한다 (언어팩 디렉토리 구조와는 별개). 어떤 템플릿이 부팅되든 자동 노출된다.

lang/
├── ko/                  # 백엔드 .php (Laravel __() / trans())
│   └── activity_log.php, admin_layout.php, auth.php, ...
├── en/                  # 백엔드 .php
│   └── activity_log.php, admin_layout.php, ...
├── partial/             # 프론트엔드 .json 분할 (선택)
│   ├── ko/
│   │   └── (영역별 .json — 필요 시)
│   └── en/
├── ko.json              # 프론트엔드 엔트리 ($t: 프리픽스)
└── en.json              # 프론트엔드 엔트리

축	코어	모듈 (sirsoft-board)	동일 패턴
백엔드 .php	lang/{ko,en}/*.php	modules/_bundled/sirsoft-board/resources/lang/{ko,en}/*.php	✓
프론트엔드 엔트리	lang/{ko,en}.json	modules/_bundled/sirsoft-board/resources/lang/{ko,en}.json	✓
프론트엔드 partial	lang/partial/{ko,en}/*.json	modules/_bundled/sirsoft-board/resources/lang/partial/{ko,en}/*.json	✓

코어 키 공간 컨벤션

코어 프론트엔드 lang JSON 의 root 키는 core.* prefix 로 일원화한다. 영역별 세분화:

• core.errors.* — 템플릿 엔진 에러 메시지 (TemplateNotFoundError 등)
• core.toast.* — 코어가 발화하는 시스템 토스트
• core.layout_editor.* — 레이아웃 편집기 chrome
• core.<영역>.* — 향후 코어 UI 추가 시

호스팅 템플릿/모듈/플러그인의 lang JSON 은 root 에 core 키를 정의하지 않는다. 정적 검사가 차단한다.

런타임 병합 흐름

TemplateService::getLanguageDataWithModules 가 다음 순서로 병합:

1. 코어 자체 (lang/{locale}.json + partial) — 가장 베이스
2. 템플릿 (templates/{id}/lang/{locale}.json)
3. 모듈 (modules/{id}/resources/lang/{locale}.json) — 식별자 wrap
4. 플러그인 (plugins/{id}/lang/{locale}.json) — 식별자 wrap
5. 활성 언어팩 (lang-packs/{id}/frontend/*.json — MergeFrontendLanguage 필터)

코어가 베이스로 들어가 가장 낮은 우선순위 — 템플릿/모듈/플러그인/언어팩이 코어 키를 덮어쓸 수 있다 (예: g7-core-ja/frontend/ko.json 이 활성화되면 일본어로 번역).

병합 정책 — Deep Merge (재귀 병합)

TemplateService::getLanguageDataWithModules 는 array_merge 가 아닌 재귀 deep merge (deepMergeLanguageData) 로 4개 레이어를 합친다. 동일 top-level 키(예: layout_editor, core, auth) 의 하위 트리를 leaf 까지 내려가며 합치고, 어느 한쪽이 다른 레이어의 부분 트리만 정의해도 나머지 형제 키가 보존된다.

• assoc 트리끼리 충돌 → 재귀 병합 (양쪽 leaf 모두 보존, 동일 leaf 는 뒤가 우선)
• list / scalar / 한쪽만 array → 뒤 입력으로 덮어쓰기
• 우선순위(낮음 → 높음): 코어 < 템플릿 < 모듈 < 플러그인 < 활성 언어팩(filter 훅)

이 정책으로 템플릿이 layout_editor.palette 만 정의해도 코어의 layout_editor.chrome / device / zoom / preview / save 가 살아남는다. 과거 shallow array_merge 는 동일 top-level 키 시 트리 전체가 교체되어, 템플릿이 한 sub-key 만 정의해도 코어의 다른 sub-key 가 통째 누락되는 결함이 발생했다.

확장 작성 시 권장 패턴:

• 코어가 정의한 도메인 네임스페이스(예: layout_editor.*, core.*, auth.*) 안에 자신의 sub-key 만 정의하면 deep merge 가 자동으로 양쪽 보존
• 코어 leaf 를 의도적으로 오버라이드하려면 동일 키 경로에 leaf 만 정의 (트리 교체 의도가 아니라 leaf override 의도임을 코드로 표현)
• 모듈/플러그인은 식별자 wrap (module.{id}.*, plugin.{id}.*) 사용을 우선 — 코어 도메인과 충돌할 일이 없고, deep merge 의 잠재적 부작용도 회피

호스팅 템플릿 무관성

코어가 자체 자원을 베이스로 제공하므로, 호스팅 템플릿이 바뀌어도 $t:core.errors.* 같은 키는 항상 해석된다. 코어가 발화하는 에러/토스트/편집기 등이 호스팅 템플릿 종속이 되지 않는다.

Manifest 명세 (language-pack.json)

언어팩 매니페스트는 모듈/플러그인/템플릿 매니페스트와 동일한 필드 구조로 정렬되어 있어 외부 작성자가 다른 확장과 동일한 표준으로 언어팩을 만들 수 있습니다.

{
    "identifier": "g7-core-ja",
    "namespace": "g7",
    "vendor": "sirsoft",
    "name": {
        "ko": "G7 코어 일본어 언어팩",
        "en": "G7 core Japanese language pack",
        "ja": "G7 コア 日本語 言語パック"
    },
    "description": {
        "ko": "G7 코어 일본어 언어팩 (번들)",
        "en": "G7 core Japanese language pack (bundled)",
        "ja": "G7 コア 日本語 言語パック(バンドル)"
    },
    "version": "1.0.0",
    "license": "MIT",
    "scope": "core",
    "target_identifier": null,
    "locale": "ja",
    "locale_name": "Japanese",
    "locale_native_name": "日本語",
    "text_direction": "ltr",
    "g7_version": ">=7.0.0",
    "requires": {
        "target_version": null,
        "depends_on_core_locale": false
    },
    "github_url": "",
    "github_changelog_url": ""
}

필드

필드	필수	설명
identifier	✓	전역 고유 — 네이밍 공식: {vendor-or-namespace}-{scope}-{target?}-{locale}
namespace	✓	식별자 prefix (예: g7, acme). identifier 의 prefix 와 일치해야 함
vendor	✓	제작자 식별자 (kebab-case). namespace 와는 의미 분리 — 동일 namespace 의 패키지를 여러 벤더가 발행 가능
name	✓	다국어 객체 — 최소 ko/en 키 + 자체 로케일 키. 카드 UI 표시명
description	✓	다국어 객체 — 동일 키 규칙. 상세 모달 설명
version	✓	semver. 번들 패키지는 패치 단위 bump 후 CHANGELOG 항목 작성
license	✓	SPDX 식별자 (예: MIT)
scope	✓	core / module / plugin / template
target_identifier	✓	scope=core 면 null, 그 외 호스트 확장 식별자
locale	✓	IETF BCP-47 (예: ja, zh-CN, pt-BR)
locale_name	✓	영문 언어명 (예: Japanese, Simplified Chinese)
locale_native_name	✓	언어 선택 UI 표시명 (예: 日本語)
text_direction	✓	ltr / rtl
g7_version	✓	코어 호환 버전 제약 (top-level — 모듈/플러그인 매니페스트와 일관). 모듈 매니페스트의 g7_version 과 동일 의미
requires.target_version	✓	scope=module/plugin/template 일 때 호스트 확장 버전 제약. scope=core 면 null
requires.depends_on_core_locale	✓	true 일 때 활성화 시 동일 locale 의 코어 언어팩 활성 상태를 강제
github_url	✓	GitHub 저장소 URL (없으면 빈 문자열). 비어있지 않으면 GitHub 기반 업데이트 경로 활성화 — 모듈/플러그인 매니페스트와 동일 동작
github_changelog_url	✓	GitHub release/CHANGELOG URL (없으면 빈 문자열)

콘텐츠 파일

매니페스트의 contents 필드는 사용하지 않습니다. 패키지 디렉토리 (lang-packs/{identifier}/) 의 backend/{locale}/, frontend/, seed/ 하위 파일이 자동 발견됩니다.

• backend/{locale}/*.php — Laravel trans() 파일 (코어/모듈/플러그인 PHP 다국어)
• frontend/{locale}.json — 템플릿 풀 페이로드
• frontend/partial/{locale}/*.json — 템플릿/모듈 partial 페이로드
• seed/{entity}.json — 다국어 시드 (NotificationDefinition, IdentityMessageDefinition 등)

들여쓰기 규칙

• language-pack.json (매니페스트) — 4-space (모듈/플러그인/템플릿 매니페스트와 일관)
• 콘텐츠 JSON (frontend/*.json, seed/*.json) — 2-space

슬롯과 다중 벤더

슬롯 = (scope, target_identifier, locale) 튜플. 동일 슬롯에 여러 벤더가 공존할 수 있으나 active 는 1개만 허용 (language_packs_slot_active_unique functional index).

slot (core, null, ja):
  - sirsoft-core-ja  (active, vendor=sirsoft)
  - acme-core-ja     (installed, vendor=acme)

UI 에서 라디오로 즉시 전환 가능. 활성 팩이 제거되면 slot 의 다음 후보가 자동 승격됩니다.

설치 흐름

1. ZIP/GitHub/URL → _pending/{tmp}/ 추출
2. LanguagePackManifestValidator → manifest 구조 검증
3. 보안 검사: backend/ 외 PHP 파일 차단, eval/include 패턴 차단
4. 의존성 검사: depends_on_core_locale=true 면 코어 언어팩 active 여부 확인
5. 대상 확장 존재 확인 (modules/plugins/templates 테이블)
6. 다운그레이드 차단 (version_compare)
7. _pending → lang-packs/{identifier}/ 이동
8. DB 레코드 생성/업데이트, 슬롯이 비어있으면 자동 active 승격
9. HookManager::doAction('core.language_packs.after_activate', $pack) → SyncDatabaseTranslations 리스너가 DB JSON 컬럼 갱신

웹 인스톨러 (public/install/) 동반 설치

신규 사이트 초기 설치 시 4단계 확장 선택 화면에서 번들 언어팩(lang-packs/_bundled/*)을 함께 선택할 수 있습니다.

• 인스톨러는 Laravel 부팅 전 단계로 동작하므로 lang-packs/_bundled/*/language-pack.json 매니페스트를 직접 스캔하여 카드를 노출합니다.
• 카드는 locale 별 서브헤딩으로 그룹핑되며, scope 가 module/plugin/template 인 항목은 종속 확장(target_identifier)이 함께 선택되어야 활성화됩니다. 종속 확장을 해제하면 그 언어팩 카드는 자동으로 비활성화 + 선택 해제됩니다.
• 코어 언어팩(scope: "core")은 target_identifier 가 없으므로 항상 활성화 상태입니다.
• default 선택 정책은 모두 OFF — 사용자가 명시 선택. (관리자 설치 모달의 "모든 후보 ON" 정책과 차별화하여, 신규 사이트가 불필요한 언어팩으로 시작하지 않도록 함.)
• 설치 실행 시 5단계의 모든 확장 install/activate 가 완료된 뒤 php artisan language-pack:install {identifier} --source=bundled 가 선택된 각 언어팩에 대해 호출됩니다(자동 활성화 default).
• 언어팩 1건 설치 실패는 best-effort 처리 — 전체 설치를 중단하지 않고 경고 로그만 남긴 뒤 다음 언어팩으로 진행합니다. 코어/모듈/플러그인 install 실패와 달리 rollback 을 발생시키지 않습니다.

프로비저닝과 드리프트 발견 (supported_locales)

코어의 ko/en 은 가상 보호 행으로 DB 설치 없이 항상 서빙되지만, 그 외 로케일(예: ja)의 번들 언어팩은 lang-packs/_bundled/ 에 소스가 있어도 설치본 디렉토리로 복사·등록되어야 서빙됩니다. 이 비대칭 때문에 "설치본이 없거나 어긋난" 상태가 오류 없이 조용히 ko 로 폴백할 수 있어, 다음 도구로 프로비저닝·발견을 지원합니다.

language-pack:provision (멱등 프로비저닝)

php artisan language-pack:provision                 # supported_locales 의 비-base 로케일을 대상으로 미설치 번들 팩 설치
php artisan language-pack:provision --locale=ja      # 특정 로케일만
php artisan language-pack:provision --scope=core     # 스코프 한정

• 대상 로케일 기본값은 config('app.supported_locales') 에서 base locale(ko/en)을 뺀 집합입니다. 즉 "사이트가 쓰겠다고 선언한 로케일" 만 채웁니다(불필요한 로케일 대량 설치 없음).
• 미설치 번들 팩(신규 설치)과 설치본 파일이 사라진 드리프트 팩(복구)을 함께 대상으로 삼습니다. 정상 설치된 팩은 어느 쪽에도 해당하지 않아 재실행해도 신규 설치가 0 건으로 수렴합니다(완전 멱등). fresh install · 복구 · 시더가 공유하는 단일 프로비저닝 경로입니다.
• 대상 확장 미설치/미활성 등 설치 차단 사유가 있는 팩은 건너뛰고 경고만 남깁니다(best-effort).

미설치·드리프트 발견

• language-pack:list 는 설치된 DB 행뿐 아니라 "번들에 있으나 미설치"(uninstalled) 및 "active 로 기록됐으나 설치본 파일 부재(드리프트)" 를 함께 표시합니다. 드리프트 행의 Status 는 active (파일 없음) 처럼 표기됩니다.
• 관리자 언어팩 목록 화면도 동일하게 드리프트 행에 "파일 없음" 배지와 원클릭 재설치 버튼을 노출합니다(번들 소스 재설치).
• 재설치 버튼은 번들 소스가 실재하는 팩에만 뜹니다. 설치 경로(zip/GitHub/URL)와 무관하게 동일 식별자의 lang-packs/_bundled/ 소스가 있으면 복구할 수 있고, 소스가 없는 서드파티 팩은 배지로 발견만 되고 복구 버튼은 뜨지 않습니다(복구할 원본이 없기 때문).

supported_locales ↔ 번들 소스 정합

config/app.php 의 supported_locales 에 비-base 로케일을 선언했다면, 대응하는 코어 번들 소스(lang-packs/_bundled/g7-core-{locale}/)가 존재해야 프로비저닝으로 채울 수 있습니다. 대응 소스가 없는 로케일을 선언하면 설치할 팩 자체가 없어 그 로케일이 조용히 ko 로 폴백합니다(복구 경로 없음). 이 정합은 정적 검사로 확인됩니다 — 소스를 추가하거나 미지원 로케일을 선언에서 제거하세요.

시더 통합 (HookManager 필터)

기존 시더에 applyFilters 1줄만 추가하면 자동으로 다국어 키가 병합됩니다.

// database/seeders/RolePermissionSeeder.php
$config = config('core.permissions');
$config = HookManager::applyFilters('core.permissions.config', $config);
foreach ($config['categories'] as $cat) { ... }

필터명	적용 위치
core.permissions.config	RolePermissionSeeder
core.roles.config	RolePermissionSeeder
core.menus.config	CoreAdminMenuSeeder
seed.notifications.translations	NotificationDefinitionSeeder
seed.identity_messages.translations	IdentityMessageDefinitionSeeder (본인인증 메일 메시지 정의 — provider × scope × scope_value 복합 키)
seed.{vendor-module}.{entity}.translations	모듈 시더 (예: seed.sirsoft-ecommerce.shipping_types.translations, seed.sirsoft-ecommerce.notifications.translations, seed.sirsoft-board.board_types.translations)
seed.{vendor-module}.identity_messages.translations	모듈/플러그인 IDV 메시지 정의 — ModuleManager::syncModuleIdentityMessages / PluginManager::syncPluginIdentityMessages 가 발화
module.{id}.admin_menus.translations	ModuleManager::createModuleMenus() — 모듈 admin_menus 동기화 시
module.{id}.roles.translations	ModuleManager::createModuleRoles() — 모듈 roles 동기화 시
module.{id}.permissions.translations	ModuleManager::createModulePermissions() — 모듈 권한 트리 동기화 시
plugin.{id}.roles.translations	PluginManager::createPluginRoles() — 플러그인 roles 동기화 시
plugin.{id}.permissions.translations	PluginManager::createPluginPermissions() — 플러그인 권한 트리 동기화 시
template.language.merge	TemplateService::getLanguageDataWithModules()

확장 시드 필터 자동 결선 (LanguagePackServiceProvider::registerExtensionSeedFilters): 활성 모듈/플러그인 언어팩의 seed/*.json 마다 위 패턴의 필터에 listener 가 자동 등록됩니다. 매칭 키는 entry 의 컬럼을 우선순위(code > slug > key > identifier > id) 로 자동 감지합니다.

엔티티별 결선 정책:

• notifications.json → seed.{target}.notifications.translations 필터 (Definition × Template 3-tier 구조)
• identity_messages.json → seed.{target}.identity_messages.translations 필터 (Definition × Template × Channel — provider/scope_type/scope_value 복합 키 매칭)
• menus.json → module.{target}.admin_menus.translations 필터 (모듈 전용)
• roles.json → {scope}.{target}.roles.translations 필터 (module/plugin)
• permissions.json → {scope}.{target}.permissions.translations 필터 (3-레벨 트리: module/categories/permissions)
• 기타 → seed.{target}.{entity}.translations 필터 (단순 entity 시드)

복원 경로의 언어팩 병합

[기본값 복원](알림 템플릿·본인인증 메시지)은 위 시딩 필터가 아니라 자체 기본값 필터 (core.notification.filter_default_definitions / core.identity.filter_default_message_definitions)를 탄다. 복원 기본값에는 활성 언어팩 seed 로케일이 반드시 병합되어야 한다 — 병합하지 않으면 복원이 팩이 주입해 둔 로케일(ja 등)을 config 의 ko/en 만으로 대체해 영구 소실시키며, 오류도 로그도 남지 않는다. 코어 서비스(NotificationTemplateService·IdentityMessageTemplateService)가 필터 적용 후 시딩과 같은 주입기(SSoT)로 병합하며, 정적 검사(테스트)가 이 계약을 고정한다.

시딩 필터의 페이로드는 발화 주체의 원형 키를 보존해야 한다 — 코어 알림 시더는 config 원형(연관 배열, 키가 곧 type), 본인인증은 복합 키(mail.purpose.signup 등)가 매칭 키다. 키를 버리고 리스트로 만들면 주입기가 전 항목을 스킵해 팩 로케일이 오류 없이 주입되지 않는다. 알림 주입기는 두 형태(문자열 키 우선, 없으면 type 필드)를 수용한다.

사용자 수정 보존 판정과 시딩 컨텍스트

언어팩 병합·제거의 사용자 수정 보존 판정은 운영자 수정의 실제 기록 형식인 dot-path 항목 (user_overrides 의 "{컬럼}.{로케일}")을 기준으로 한다. 컬럼 전체 항목("subject")은 시더 재실행의 컬럼 보호 선언이며 팩 병합을 막지 않는다 — 막으면 팩 업데이트가 자기 로케일 번역을 갱신하지 못한다.

이를 위해 두 가지가 함께 지켜져야 한다:

• 다국어 JSON 컬럼을 추적하는 모델은 translatableTrackableFields 를 선언한다 — 미선언 시 운영자 수정이 컬럼 전체 항목으로 기록되어 로케일 단위 보존이 불가능해진다.
• 언어팩 주입·제거처럼 시스템이 수행하는 저장은 시딩 컨텍스트(user_overrides.seeding 바인딩) 안에서 실행한다 — 바인딩 없이 저장하면 주입 자체가 "사용자 수정"으로 오인 기록되어 이후 시더 재실행의 컬럼 갱신이 영구히 얼어붙는다.

실패한 업데이트의 상태 복원

language-pack:update 가 설치 트랜잭션 이후(활성화 단계)에 실패하면 팩 상태를 이전 상태로 복원한다. 복원하지 않으면 active 였던 팩이 installed 로 방치되어 해당 로케일의 백엔드 번역이 안내 없이 기본 로케일로 폴백된다.

같은 프로세스 활성화와 필터 인스턴스

시더 번역 필터 클로저는 boot 시점의 injector→registry 인스턴스를 캡처한다. 활성 팩 목록 캐시를 갱신할 때는 싱글톤을 유지한 채 LanguagePackRegistry::invalidate() 로 내부 캐시만 비운다 — forgetInstance 로 바인딩을 교체하면 캡처된 구 인스턴스의 stale 캐시가 남아, 같은 프로세스에서 활성화된 신규 팩이 시더 필터에 보이지 않는다(오류 없이 해당 로케일만 미주입).

IDV 도메인 lang pack 커버리지

config/core.php 의 본인인증 SSoT 4개 블록 중 lang pack seed 대상은 1개:

SSoT 블록	lang pack seed	사유
notification_definitions	✓ seed/notifications.json	정의/템플릿이 다국어 데이터 직접 보유
identity_messages	✓ seed/identity_messages.json	메일 본문/제목이 다국어 데이터 직접 보유
identity_policies	❌	IdentityPolicy 모델에 다국어 필드 부재 — 관리자 UI 라벨은 lang/{locale}/identity.php 또는 frontend/partial/admin.json 의 i18n 키로 처리
identity_purposes	❌	label_key/description_key 참조 패턴 — 실제 ja 라벨은 frontend/partial/admin.json::identity.purposes.* 키로 처리

identity_messages.json 스키마 예시:

{
  "mail.purpose.signup": {
    "definition": {
      "name": "会員登録認証",
      "description": "会員登録時のメール認証"
    },
    "templates": {
      "mail": {
        "subject": "[アプリ] 会員登録認証コード",
        "body": "<p>認証コード: {code}</p>"
      }
    }
  }
}

복합 키는 {channel}.{scope_type}.{scope_value} 또는 {channel}.provider_default 형태 — config/core.php::identity_messages 의 array key 와 동일.

확장 권한 트리 시드 키 포맷: 권한은 ModuleManager 가 DB row identifier 를 {module-id}.{cat-id}.{perm-id} 로 prefix 하므로 시드도 동일 포맷을 사용합니다. 권한 노드 식별자는 action(이커머스 등) 또는 identifier(명시적) 둘 중 존재하는 키를 사용합니다.

user_overrides 보존 정책

HasUserOverrides 사용 모델(Permission/Role/Menu/NotificationDefinition/NotificationTemplate/Module/Plugin/Template)에서 사용자가 직접 수정한 컬럼/locale 키는 언어팩이 덮어쓰지 않습니다.

케이스	동작
A: 기존 row 에 해당 locale 키 부재	추가 (overrides 무관)
B: locale 키 존재 + user_overrides 등록	건너뜀 (사용자 보존)
C: locale 키 존재 + user_overrides 미등록	시드 값으로 덮어쓰기

비활성화/제거 시에도 user_overrides 등록 locale 은 JSON 에서 제거되지 않습니다. 모든 보존 결정은 language_pack 채널에 감사 로그로 기록됩니다.

백엔드 번역 namespace fallback 메커니즘

Laravel Translator 의 FileLoader 는 addNamespace($namespace, $hint) 가 단일 hint 만 보유하며 덮어쓰는 구조이므로, 모듈/플러그인 자체의 src/lang namespace 등록 후 같은 namespace 로 언어팩이 추가되면 모듈의 ko/en 등록이 통째로 사라지는 회귀가 발생합니다.

LanguagePackTranslator 가 이를 회피하기 위한 namespace fallback 경로를 별도 보유합니다.

• addNamespaceFallbackPath($namespace, $locale, $path) — namespace ⇒ locale ⇒ 경로 배열로 누적 등록
• load($namespace, $group, $locale) — 표준 hint 로 1차 로드 후 namespace fallback 경로의 PHP 배열 파일을 누락 키만 보완 병합 (기존 번역 우선)

이 메커니즘으로 모듈은 src/lang/{ko,en}/*.php 의 표준 namespace 등록을 그대로 유지하고, 활성 ja 언어팩은 fallback 경로(lang-packs/g7-module-{id}-ja/backend/ja/) 에서만 ja 키를 보완합니다.

프론트엔드 다국어 병합의 wrap 정책

MergeFrontendLanguage 가 활성 언어팩의 frontend/*.json 을 병합할 때 scope 별로 root key 처리가 다릅니다.

• core / template scope — root 에 평탄 병합 (TemplateService 의 ko 데이터 구조와 일치)
• module / plugin scope — [$pack->target_identifier => $frontend] 로 wrap 후 병합

wrap 이 필요한 이유: TemplateService 가 모듈/플러그인 자체 ko 데이터를 [$identifier => $data] 로 wrap 하므로, 언어팩 데이터도 동일 구조여야 $t:sirsoft-ecommerce.admin.* 같은 표현식이 ja 활성 시에도 정확한 경로로 해석됩니다.

권한

권한	설명
core.language_packs.read	언어팩 목록 및 상세 조회
core.language_packs.install	ZIP/GitHub/URL 설치
core.language_packs.manage	활성화/비활성화/제거

REST API

엔드포인트	메서드	권한
/api/admin/language-packs	GET	read
/api/admin/language-packs/{id}	GET	read
/api/admin/language-packs/install-from-file	POST	install
/api/admin/language-packs/install-from-github	POST	install
/api/admin/language-packs/install-from-url	POST	install
/api/admin/language-packs/{id}/activate	POST	manage
/api/admin/language-packs/{id}/deactivate	POST	manage
/api/admin/language-packs/{id}	DELETE	manage

보안

1. ZIP slip 방지 — ZipInstallHelper 의 기존 검증 재사용
2. PHP 격리 — backend/ 디렉토리 외 PHP 파일 거부
3. 위험 함수 차단 — eval/include/require/exec/system/popen 등 정적 분석으로 거부
4. 파일 크기 제한 — 10MB
5. 체크섬 검증 — URL 설치 시 SHA-256 옵션

외부 패키지형 vs 메타데이터 전용 번들

번들 언어팩은 두 가지 형태를 가질 수 있습니다.

형태	contents	실제 번역 자산 위치	사용 사례
메타데이터 전용	빈 배열	코어/확장 트리(lang/{locale}/, templates/_bundled/*/lang/{locale}.json)	코어 fallback locale (ko/en) — 트리 자체에 포함된 자산을 시스템에 등록만 하기 위함
외부 패키지형	실제 파일 경로	패키지 디렉토리 내(backend/{locale}/*.php, frontend/*.json, seed/*.json)	추가 로케일 (ja, zh-CN 등) — 코어 트리를 건드리지 않고 새 locale 추가

기본 ko/en 은 메타데이터 전용 — 실제 PHP/JSON 파일은 코어 트리에 그대로 두고 manifest 1개로 시스템에 등록만 합니다. 새 locale (예: 일본어) 은 외부 패키지형으로 도입하여 코어 코드 변경 0 을 유지합니다.

공식 일본어 번들 언어팩 (g7-*-ja)

G7 는 일본어 번들 언어팩 12종을 공식 제공합니다. ko 원본을 LLM 으로 자동 번역하여 빌드된 산출물이며, 사용자 환경에서는 일반 번들 확장과 동일하게 language-pack:install --source=bundled 로 설치합니다.

패키지 구성

scope	식별자	target_identifier
core	g7-core-ja	(null)
template	g7-template-sirsoft-admin_basic-ja	sirsoft-admin_basic
template	g7-template-sirsoft-basic-ja	sirsoft-basic
template	g7-template-gnuboard7-hello_admin_template-ja	gnuboard7-hello_admin_template
template	g7-template-gnuboard7-hello_user_template-ja	gnuboard7-hello_user_template
module	g7-module-sirsoft-ecommerce-ja	sirsoft-ecommerce
module	g7-module-sirsoft-board-ja	sirsoft-board
module	g7-module-sirsoft-page-ja	sirsoft-page
module	g7-module-gnuboard7-hello_module-ja	gnuboard7-hello_module
plugin	g7-plugin-sirsoft-ckeditor5-ja	sirsoft-ckeditor5
plugin	g7-plugin-sirsoft-marketing-ja	sirsoft-marketing
plugin	g7-plugin-sirsoft-tosspayments-ja	sirsoft-tosspayments

입력 → 산출 매핑

패키지	ko 원문 소스	산출 위치
g7-core-ja backend	lang/ko/*.php (33개)	lang-packs/_bundled/g7-core-ja/backend/ja/*.php
g7-core-ja seed	config/core.php (permissions/roles/menus) + NotificationDefinitionSeeder	seed/{permissions,roles,menus,notifications}.json
g7-template-{tpl}-ja	templates/_bundled/{tpl}/lang/ko.json + lang/partial/ko/*.json	frontend/ja.json + frontend/partial/*.json
g7-module-{mod}-ja	modules/_bundled/{mod}/{src,resources}/lang/ko/*.php + resources/lang/ko.json + resources/lang/partial/ko/**/*.json (재귀)	backend/ja/*.php + frontend/ja.json + frontend/partial/**/*.json
g7-module-sirsoft-ecommerce-ja seed	ShippingTypeSeeder, ClaimReasonSeeder, EcommerceNotificationDefinitionSeeder ko 추출	seed/{shipping_types,claim_reasons,notifications}.json
g7-module-sirsoft-board-ja seed	BoardTypeSeeder::DEFAULT_BOARD_TYPES 상수 추출	seed/board_types.json
모듈 ja 팩 (공통)	module.php 의 getAdminMenus / getRoles / getPermissions 추출	seed/{menus,roles,permissions}.json
플러그인 ja 팩 (공통)	plugin.php 의 getRoles / getPermissions 추출	seed/{roles,permissions}.json
모든 확장 ja 팩	module.json / plugin.json / template.json 의 name/description ko	seed/manifest.json
g7-plugin-{pl}-ja	plugins/_bundled/{pl}/lang/ko/*.php	backend/ja/*.php

빌드 source kind

kind	동작
php-dir	디렉토리의 모든 *.php 를 ko → ja 로 번역
json-file	단일 JSON 파일 ($partial 디렉티브 경로 정규화 포함)
json-dir	디렉토리의 모든 .json 재귀 (admin/ 같은 서브디렉토리 포함)
core-seed	config/core.php 에서 permissions/roles/menus ko 추출
notif-seed	NotificationDefinitionSeeder 의 getDefaultDefinitions 추출
ext-seed	확장 시더의 메서드/상수 추출 (entity 별 매칭 키 자동 감지)
ext-spec-seed	module.php / plugin.php 의 getAdminMenus / getRoles / getPermissions 결과 추출. 권한은 {module-id}.{cat-id}.{perm-id} prefixed identifier 로 출력
manifest-seed	manifest 파일의 name/description ko 추출 → seed/manifest.json

번역 규칙

• placeholder 보존: :attribute, {count}, {{var}}, %s, :other
• HTML 태그 보존: <a>, <br>, <strong>, <span>
• 키(key) 변형 금지 — value 만 번역
• 통화/숫자 단위 변환 금지 (런타임 처리)
• 공식체(です·ます) 강제, 친근체 금지
• 한글 미포함 value(영문/숫자/기호만) 는 번역 스킵 → 원문 유지
• 고정 용어집으로 일관성 강제 (예: 관리자 → 管理者, 장바구니 → カート)

용어집 등록 의무

번역 결과의 표기는 고정 용어집이 정한다. 용어집에 없는 도메인 용어는 어간만 번역되어 원본 로케일 문자가 값에 그대로 남는다 — 예외도 오류도 나지 않고, 키 대칭 검사도 값은 보지 않으므로 그 로케일로 화면을 열기 전까지 드러나지 않는다.

• 새 도메인 용어를 도입하면 번역 빌드 전에 용어집에 등록한다
• 이미 생성된 값을 손으로 고쳤다면 용어집도 함께 고친다 — 용어집을 두면 다음 키에서 같은 오역이 되풀이된다
• 같은 용어는 팩 전체에서 한 표기로 통일한다 (용어집이 단일 출처)

정적 검사가 번역 값의 원본 로케일 문자 잔존을 검출한다. 매니페스트와 CHANGELOG, 그리고 한국어 주석은 대상이 아니다.

설치 및 활성화

# 12개 패키지를 번들 소스로 설치 (자동 활성)
php artisan language-pack:install g7-core-ja --source=bundled
php artisan language-pack:install g7-template-sirsoft-admin_basic-ja --source=bundled
# ... (나머지 10개 동일)

# 확인
php artisan language-pack:list --scope=core
php artisan language-pack:list --scope=module

기존 ko/en 변경 시 번들 ja 동기화 의무

코어/모듈/플러그인/템플릿의 ko 또는 en 다국어 키를 추가/수정/제거할 때마다 대응하는 번들 ja 패키지(lang-packs/_bundled/g7-*-ja/) 의 키 셋을 동기화해야 한다. 동기화하지 않으면 일본어 화면에서 미번역 fallback(ko/en) 이 노출되어 UX 가 손상된다.

번들 ja 동기화/빌드 자동화 도구는 메인테이너 영역이며, 외부 기여자는 ko 원본 변경 후 PR 시 메인테이너가 동기 빌드를 수행한다. 자기 환경에서 검증이 필요하다면 ko 키를 직접 ja 패키지의 대응 위치(lang-packs/_bundled/g7-*-ja/backend/ja/, frontend/, seed/) 에 수동 추가/수정/삭제할 수 있다 — 키만 일치하면 시스템이 정상 fallback 한다.

잉여 키 (ko 에서 제거 후 번들 잔류) 처리

ko 에서 키 제거 시 번들 ja 의 대응 키도 수동 제거 권장 (자동 제거 도구 없음 — 의도치 않은 제거 방지).

번들 언어팩 버전 + CHANGELOG 작성 규정

번들 언어팩 자산을 수정할 때마다 모듈/플러그인/템플릿 확장과 동일한 수준의 버전 + CHANGELOG 관리를 적용한다.

• 버전 bump 시점: 패키지가 외부에 한 번이라도 출시(릴리즈/배포) 된 이후의 수정에 한해 버전을 올린다. 아직 출시되지 않은 번들 패키지의 사전 보강(키 추가/번역 정정 등) 은 1.0.0 그대로 유지한다. 이미 출시된 버전의 콘텐츠를 수정하면 patch bump 가 필수다 (출시 확정 버전의 콘텐츠를 버전 유지한 채 덮어쓰지 않는다).
• 버전 bump 단위: 출시 후 키 추가/누락 보강은 패치 (1.0.0 → 1.0.1), 의미적으로 큰 변경이나 제거는 마이너 (1.0.0 → 1.1.0).
• CHANGELOG.md: 패키지 루트에 CHANGELOG.md 작성. Keep a Changelog 표준 (## [버전] - YYYY-MM-DD + ### Added/Changed/Fixed/Removed).
• 톤: 사용자 관점, 1~2줄 불릿. 내부 파일 경로/내부 함수명/이슈 번호 미기재.
• 신규 기능의 개발 중 결함: 같은 릴리즈에 처음 도입된 키의 누락 보강 등은 Fixed 가 아닌 Added 로 기록.
• 번역 자체 수정 (예: 어색한 표현 교정): ### Changed 로 기록.
• 자동화: 빌드 스크립트는 기존 manifest 의 version 을 읽어 보존하므로, 수동 bump 한 1.0.1 등이 다음 빌드에서 1.0.0 으로 덮어쓰이지 않는다.

외부 언어팩 패키지 개발 · 배포

번들 ja 와 동일한 디렉토리 구조의 언어팩 패키지를 자체 작성하여 별도 배포할 수 있다. 코어 트리는 변경하지 않으므로 코어 업데이트와 충돌하지 않는다.

my-lang-pack-zh/
├── language-pack.json          # 매니페스트 (식별자, scope, target_identifier, locale, version, manifest 키 셋)
├── backend/
│   └── zh-CN/                  # 백엔드 PHP 키 (스코프가 코어/모듈/플러그인일 때)
│       └── *.php
├── frontend/                   # 프론트엔드 JSON 키 (스코프가 모듈/플러그인/템플릿일 때)
│   ├── zh-CN.json
│   └── partial/
│       └── *.json
└── seed/                       # 초기 데이터 번역 (스코프별 entity 키 매칭 — permissions/menus/notifications 등)
    └── *.json

매니페스트(language-pack.json) 필드는 번들 ja 패키지를 참고. scope 는 core/module/plugin/template 중 하나, target_identifier 는 대상 확장 식별자(코어 스코프는 null), locale 은 BCP 47 코드.

설치

# 로컬 디렉토리에서 설치
php artisan language-pack:install /path/to/my-lang-pack-zh --source=local

# 또는 zip 으로 배포 후 URL 에서 설치
php artisan language-pack:install https://example.com/my-lang-pack-zh.zip --source=url

설치 후 language-pack:list 로 확인. 다른 로케일 패키지와 동일하게 활성/비활성/제거가 가능하며, 의존성 검증(core_locale_missing 등) 도 동일하게 적용된다.

의존성 검증 — 설치 차단 사유 (UI 인라인 안내)

미설치 번들 행과 설치 모달은 다음 4가지 사유로 설치 차단을 표시한다 (LanguagePackService::resolveInstallBlockedReason() 가 단일 SSoT). 모듈/플러그인 시스템과 동일 강도.

사유 키	발생 조건
core_locale_missing	scope ≠ core + 코어 동일 locale 팩 미활성
target_not_installed	대상 모듈/플러그인/템플릿이 DB 에 없음
target_inactive	대상은 설치되었지만 status ≠ active
target_version_too_old	manifest requires.target_version 미충족

LanguagePackResource::resourceMeta() 가 차단 사유 존재 시 abilities.can_install 을 false 로 강제 — UI 행/모달 버튼이 권한과 무관하게 disabled.

is_protected 정책 (모듈/플러그인/템플릿과 일관)

번들 언어팩(lang-packs/_bundled/*) 은 manifest 의 is_protected 선언을 따른다. 기본값은 false — 모듈/플러그인/템플릿이 번들이라도 자유 제거 가능한 것과 동일.

LanguagePackBundledRegistrar 가 동기화하는 bundled_with_extension 레코드(모듈/플러그인/템플릿 자체에 포함된 lang 디렉토리에서 자동 등록되는 가상 행) 만 is_protected: true 로 고정 — 부모 확장 lifecycle 에 종속되어 독립 제거가 불가하기 때문.

Manifest 미리보기 (3종 확장과 동등)

ZIP 업로드 전 manifest 검증 결과를 사전 확인할 수 있다. 모듈/플러그인/템플릿 시스템에도 동일 패턴으로 추가됨.

• 라우트: POST /api/admin/{language-packs|modules|plugins|templates}/manifest-preview
• 응답: { manifest, validation: { errors[], is_valid, already_installed, existing_version } }
• 검증 실패 시에도 HTTP 200 — validation.is_valid: false + errors[] 노출
• UI: 각 도메인의 수동 설치 모달(_modal_manual_install.json) 에 "manifest 미리보기" 버튼 → 별도 드로어 partial(_drawer_manifest_preview.json) 로 ZIP 업로드 + 결과 표시
• 드로어 작성 패턴: modal-usage.md ZIP 파일 업로드 모달/드로어 패턴

관련 파일

• app/Models/LanguagePack.php
• app/Services/LanguagePackService.php
• app/Services/LanguagePack/LanguagePackRegistry.php
• app/Services/LanguagePack/LanguagePackManifestValidator.php
• app/Services/LanguagePack/LanguagePackSeedInjector.php
• app/Services/LanguagePack/LanguagePackTranslator.php
• app/Listeners/LanguagePack/SyncDatabaseTranslations.php
• app/Listeners/LanguagePack/MergeFrontendLanguage.php
• app/Providers/LanguagePackServiceProvider.php
• app/Http/Controllers/Api/Admin/LanguagePackController.php
• database/migrations/2026_04_27_000001_create_language_packs_table.php
• templates/_bundled/sirsoft-admin_basic/layouts/admin_language_pack_list.json