언어 전환 · 다국어

InfraGuard 는 한국어를 본사 기본으로, 영어를 글로벌 폴백으로 하는 8개국어 콘솔입니다. 이 문서는 (1) 사용자가 상단 스위처로 언어를 바꾸는 방법, (2) 매 요청에서 표시 언어가 결정되는 규칙, (3) 관리자가 스위처에 노출할 언어 집합을 고르는 방법을 다룹니다.

개요 — 무엇을 하나

콘솔의 모든 라벨·메뉴·메시지는 하드코딩 영문이 아니라 번역 키(__('menu.security') 등)를 경유합니다. 언어를 바꾸면 서버가 다음 요청부터 해당 로케일의 번역 파일(resources/lang/{locale}/*.php)로 UI 를 렌더합니다.

지원 언어(카탈로그)는 config/locales.php 의 admin 8종입니다. 각 언어는 활성 로케일과 무관하게 항상 그 언어의 이름(네이티브 라벨) 으로 표기됩니다.

초기에는 ko·en 만 실번역되어 있습니다(config/locales.php 의 priority => ['ko','en']). 나머지 6종(ja·zh·es·fr·de·ru)은 번역 파일이 아직 없어 자동으로 en 으로 폴백됩니다(config/app.php 의 fallback_locale = en). 즉 지금 ja 를 골라도 미번역 문자열은 영어로 표시됩니다 — 스위처는 8종을 모두 노출하되 문구만 폴백됩니다.

언제 쓰나

• 방문자가 자신에게 익숙한 언어로 콘솔을 보고 싶을 때 — 상단 언어 스위처를 씁니다.
• 로그인 화면(세션 확립 전)에서도 언어를 바꾸고 싶을 때 — /lang/{locale} 은 게스트도 허용됩니다.
• 조직 전체에 특정 언어만 노출하고 첫 방문 기본 언어를 지정하고 싶을 때 — 관리자가 활성 언어 집합·순서를 편집합니다(아래 "활성 언어 관리").

화면 구성

상단 언어 스위처(모든 화면)

헤더의 언어 드롭다운(layouts.partials.locale-switch + ui/locale-dd.js)에는 관리자가 켠 활성 언어만 나열됩니다. 각 항목은 네이티브 라벨과 짧은 태그(예: KO, EN)를 보여주고, 현재 로케일은 활성 표시(active)됩니다.

관리자 ▸ 다국어(활성 언어 관리)

Administration ▸ Localization 화면(우측 상단 버튼으로 이동)에서 8종 카탈로그를 대상으로:

• 각 언어의 활성/비활성 토글(스위처 노출 여부)
• 드래그로 표시 순서 변경 — 맨 위 활성 언어가 곧 사이트 기본 언어(primary) 가 됩니다
• 저장 시 최소 1개 언어 강제(0개 저장 거부)

사용법

1) 상단 스위처로 바꾸기

1. 헤더의 언어 드롭다운을 엽니다.
2. 원하는 언어를 고릅니다 → 브라우저가 GET /lang/{locale} 로 이동합니다.
3. 서버가 선택을 저장하고 직전 페이지로 되돌립니다(redirect()->back()). 다음 렌더부터 해당 언어로 표시됩니다.

전환 엔드포인트는 다음과 같습니다:

GET /lang/ko      # 한국어로 전환
GET /lang/en      # 영어로 전환
GET /lang/ja      # 일본어(미번역 → en 폴백)

전환 시 서버(LocaleController@switch)가 하는 일:

로그인한 사용자가 언어를 바꾸면 users.lang(프로필 언어)에도 영속화되어 다음 로그인에도 그 언어가 유지됩니다. 미로그인(게스트) 상태의 선택은 세션·쿠키로만 유지됩니다.

미지원(또는 관리자가 끈) 코드로 /lang/{locale} 을 호출하면 조용히 무시되고 현재 언어가 유지됩니다. 오류를 던지지 않습니다.

2) 표시 언어가 결정되는 규칙(SetLocale)

SetLocale 미들웨어가 모든 web 요청(로그인 화면 포함)에서 아래 우선순위로 로케일을 정합니다. 각 후보는 현재 활성 언어일 때만 채택됩니다.

1. 세션 infr_locale   (이번 세션에서 스위처로 명시 선택)
2. 쿠키 infr_locale   (방문 간 지속 선택 · 세션 확립 전 로그인 화면에도 적용)
3. 세션 infr_lang     (로그인 사용자 프로필 users.lang → 로그인 시 세션에 적재)
4. 사이트 전역 기본     (Locales::primary() = 활성 목록의 첫 언어)

브라우저 Accept-Language 자동감지는 하지 않습니다. 세션·쿠키·프로필 선택이 하나도 없는 첫 방문은, 브라우저 언어가 아니라 관리자가 정한 사이트 기본 언어로 결정적으로 제공됩니다(site-wide 권위). 방문자는 언제든 상단 스위처로 바꿀 수 있습니다.

3) 활성 언어 관리(관리자)

1. Administration ▸ Localization 로 이동합니다.
2. 노출할 언어를 토글로 켜고(스위처·전환·프로필·인벤토리 다국어 편집이 전부 이 집합을 경유), 끌 언어는 끕니다.
3. 드래그로 순서를 바꿉니다 — 맨 위 활성 언어가 기본 언어가 됩니다.
4. 저장합니다. 저장은 infr_audit_log 에 localization.save 로 감사 기록됩니다.

활성 언어를 줄이면 헤더 스위처의 가용성이 곧바로 축소됩니다. 안전장치로 최소 1개 언어는 반드시 활성이어야 하며(0개 저장은 422 로 거부), 유효 코드가 하나도 남지 않으면 시스템이 전체 카탈로그로 폴백해 항상 최소 1개를 보장합니다.

데이터 소스

활성 언어·순서 설정은 App\Support\Locales 가 60초 캐시로 읽습니다. DB 오류·미설정 시 빈 배열로 안전 폴백(→ 전체 카탈로그). 저장 후에는 Locales::flush() 로 캐시를 즉시 무효화합니다.

-- 활성 언어 집합과 순서가 저장되는 곳(예시)
SELECT `group`, `key`, `value` FROM infr_setting WHERE `group` = 'i18n';
-- group | key     | value
-- i18n  | order   | ko,en,ja,zh,es,fr,de,ru
-- i18n  | enabled | ko,en

프런트엔드로의 전달

서버는 활성 로케일과 메시지 팩을 뷰 부트스트랩으로 내려줍니다(예: window.__t = @json(__('msg')), window.__locale). Vue 페이지·믹스인은 이 값을 사용해 클라이언트측 문자열·날짜 포맷을 활성 UI 로케일에 맞춥니다.

권한

• 언어를 바꾸는 것 자체는 누구나 할 수 있습니다(민감 작업이 아님).
• 스위처에 노출할 언어 집합을 결정하는 관리 화면은 관리자 전용입니다: 라우트 그룹 infr.level:10 + 컨트롤러 자체 가드(user_level >= 10)의 이중 방어. 등급 체계는 demo=1 · staff=5 · admin=10 입니다(등급·RBAC 참조).

문제해결 · FAQ

스위처에 원하는 언어가 안 보입니다

그 언어가 관리자에 의해 비활성되어 있을 가능성이 높습니다. Administration ▸ Localization 에서 활성 토글을 켜라. 스위처·전환·프로필 언어는 전부 활성 집합을 경유합니다.

언어를 바꿨는데 일부 문구가 여전히 영어입니다

ja·zh·es·fr·de·ru 는 아직 실번역 파일이 없어 en 으로 폴백됩니다(초기 전략). 미번역 문자열만 영어로 보이는 것이 정상입니다. ko·en 은 완전 번역되어 있습니다.

첫 방문 때 내 브라우저 언어로 안 열립니다

의도된 동작입니다. InfraGuard 는 Accept-Language 를 감지하지 않고, 관리자가 지정한 사이트 기본 언어(활성 목록의 첫 언어)로 첫 화면을 엽니다. 스위처로 바꾸면 세션·쿠키에 저장되어 다음 방문부터 유지됩니다.

로그아웃 후 다시 로그인하면 언어가 초기화됩니다

쿠키(infr_locale, 1년)가 남아 있으면 유지됩니다. 로그인 사용자라면 users.lang 에도 저장되어 다음 로그인에서 프로필 언어로 복원됩니다. 쿠키·프로필이 모두 없으면 사이트 기본 언어로 열립니다.

/lang/xx 처럼 없는 코드를 넣으면?

미지원 코드는 조용히 무시되고 현재 언어가 유지됩니다(오류 없음). 지원 코드는 활성 8종 중 관리자가 켠 것들뿐입니다.

활성 언어를 전부 끄면?

막혀 있습니다. 저장 시 최소 1개 강제(0개 저장은 422 거부). 설령 설정이 손상되어도 시스템이 전체 카탈로그로 폴백해 스위처가 비지 않도록 보장합니다.

관련 항목

• 관리자 ▸ 다국어(활성 언어 관리)
• 내 프로필 · 언어
• 탐색 · 메뉴 구조
• 테마 전환(라이트·다크)
• 등급 · RBAC
• 이 매뉴얼 사용법