Gnuboard7/docs/backend/settings-multilingual-enrichment.md

Settings 카탈로그 다국어 자동 보강

TL;DR (5초 요약)

1. settings JSON 의 다국어 카탈로그 라벨(_cached_name 등)은 카탈로그 빌드 시점에 보강
2. helper: localize_catalog_field($field, $langKey) — 단일 함수 호출
3. 모듈/플러그인 Service 가 자기 빌드 메서드 안에서 직접 호출
4. lang key segment 는 settings JSON 의 식별자(id/code/key) 와 동일
5. 정적 검사가 호출 누락 검출 (경고)

사용법

Helper

app/Helpers/locale_helpers.php 의 localize_catalog_field():

/**
 * Settings 카탈로그 다국어 JSON 필드에 활성 언어팩 키 자동 보강.
 *
 * 운영자 편집값(비어있지 않은 값)은 보존, 부재한 locale 만 lang pack 에서 채움.
 *
 * @param  array<string, string>  $field    ['ko' => '...', 'en' => '...']
 * @param  string                  $langKey  완전한 lang key (네임스페이스 prefix 포함)
 * @return array<string, string>             보강된 다국어 JSON
 */
function localize_catalog_field(array $field, string $langKey): array;

모듈/플러그인 Service 사용 예 (실제 EcommerceSettingsService)

private function getBuiltinPaymentMethods(): array
{
    $defaults = $this->getDefaults();
    $methods = $defaults['defaults']['order_settings']['payment_methods'] ?? [];

    return array_map(function (array $method) {
        $id = $method['id'];

        return [
            'id' => $id,
            // 카탈로그 빌드 시점에 직접 보강
            'name' => localize_catalog_field(
                $method['_cached_name'] ?? ['ko' => $id, 'en' => $id],
                "sirsoft-ecommerce::settings.payment_methods.{$id}.name",
            ),
            'description' => localize_catalog_field(
                $method['_cached_description'] ?? ['ko' => '', 'en' => ''],
                "sirsoft-ecommerce::settings.payment_methods.{$id}.description",
            ),
            // ...
        ];
    }, $methods);
}

빌드 단계가 따로 없는 카탈로그 (currencies / countries)

settings 응답 빌드 메서드 안에서 inline foreach 로 호출:

public function getAllSettings(): array
{
    // ... settings 머지 ...

    if (isset($settings['language_currency']['currencies'])) {
        foreach ($settings['language_currency']['currencies'] as $idx => $currency) {
            if (! empty($currency['code']) && isset($currency['name']) && is_array($currency['name'])) {
                $settings['language_currency']['currencies'][$idx]['name'] = localize_catalog_field(
                    $currency['name'],
                    "sirsoft-ecommerce::settings.currencies.{$currency['code']}.name",
                );
            }
        }
    }

    return $settings;
}

Lang 파일 작성

{module|plugin}/_bundled/{id}/{src/}lang/{ko,en}/settings.php. lang key 의 segment 는 settings JSON 의 식별자(id/code/key) 와 정확히 일치해야 함.

// modules/_bundled/sirsoft-ecommerce/src/lang/ko/settings.php
return [
    'payment_methods' => [
        'card' => ['name' => '신용카드', 'description' => '신용카드로 안전하게 결제'],
        'dbank' => ['name' => '무통장입금', 'description' => '지정 계좌로 직접 입금'],
        // settings JSON 의 id 를 그대로 사용
    ],
];

ja/zh 등 다른 locale 은 번들 lang pack 자동 빌드 (build-language-pack.cjs).

운영자 편집 보존

helper 동작:

• field[locale] 이 존재하고 비어있지 않으면 → 그대로 유지 (운영자 편집값 보존)
• 키 부재 또는 빈 문자열 → lang pack 에서 채움
• lang pack 에도 키 부재 → 변경 없음

운영자가 admin UI 에서 ja 라벨을 직접 입력했다면 보존. 입력 안한 locale 만 lang pack 으로 채움.

정적 검사

경고 수준으로 다음을 검출한다:

• {modules|plugins}/_bundled/*/config/settings/defaults.json 에 다국어 카탈로그 entry 발견
• 같은 확장의 src/Services/*.php 안에 localize_catalog_field 호출 없음
• → warning (호출 누락 안내)

신규 모듈/플러그인 개발자가 카탈로그 추가 시 helper 호출을 빠뜨리지 않도록 안내.

함정 — settings JSON id 와 lang key 일치

settings JSON 의 entry 식별자(id/code/key) 와 lang 파일의 segment 가 다르면 보강이 동작하지 않음.

// defaults.json
{ "id": "dbank", "_cached_name": { "ko": "무통장입금", "en": "Bank Transfer" } }

// lang/ko/settings.php — 키가 'dbank' 이어야 함
'payment_methods' => [
    'dbank' => ['name' => '무통장입금'],   // ✓ id 와 일치
    // 'bank_transfer' => [...]            // ✗ 보강 안됨
],

참고

• Helper: localize_catalog_field()
• 적용 사례: EcommerceSettingsService::getBuiltinPaymentMethods(), getAllSettings() inline 보강
• Feature 테스트: EcommerceSettingsLocalizationTest