언어 감지 로직 상세한 내용 추가

Author: kargnas

README.md

@@ -131,12 +131,59 @@ Route::localized(function () {
     // 특별 매핑 관계 (서로 대체 가능한 언어들)
     'locale_mappings' => [
         // 번체 중국어 상호 참조 (zh_HK와 zh_TW는 모두 번체 중국어라 서로 대체 가능)
+        // 중국어 홍콩/대만 버전 차이점은 https://kargn.as/posts/differences-hong-kong-taiwan-chinese-website-ui-localisation 참고
         'zh_HK' => 'zh_TW',
         'zh_TW' => 'zh_HK',
     ],
 ],
 ```
 
+#### 언어 감지 메커니즘
+
+본 패키지는 다음과 같은 순서와 우선순위로 사용자의 언어를 감지합니다:
+
+1. **URL 경로 분석**: URL 경로에 언어 코드가 포함된 경우 이를 우선 사용
+   - 예: `/ko_KR/about` 경로에서 `ko_KR` 감지
+
+2. **쿠키 기반 감지**: 이전에 저장된 언어 설정이 있는 경우 해당 언어로 리다이렉트
+   - 쿠키에 저장된 언어가 URL 경로와 다를 경우 쿠키 값 기준으로 리다이렉트
+
+3. **브라우저 언어 감지**: 사용자 브라우저의 `Accept-Language` 헤더 분석
+   - 경로에 언어가 없거나 기본 언어일 때 브라우저 언어가 다르면 해당 언어로 리다이렉트
+
+4. **기본 언어 적용**: 위 모든 방법으로 언어를 감지하지 못한 경우 기본 언어 사용
+
+##### 언어 매칭 알고리즘
+
+`LocaleMatcher` 클래스는 브라우저나 쿠키에서 감지한 언어를 지원 언어와 매칭할 때 다음 순서로 처리합니다:
+
+1. **정확한 일치**: 완전히 동일한 언어 코드 확인 (예: `ko_KR` → `ko_KR`)
+
+2. **특별 매핑 확인**: `locale_mappings` 설정에 정의된 대체 가능 언어 확인
+   - 예: `zh_HK`가 감지되었고 설정에 `'zh_HK' => 'zh_TW'`가 있으면 `zh_TW` 사용
+
+3. **기본 언어 코드 매칭**: 언어 코드의 기본 부분만 일치하는지 확인
+   - 예: 브라우저에서 `zh`가 감지되면 `supported` 배열에서 처음 나오는 `zh_` 로케일 선택
+   - 이때 배열 순서가 중요: `zh_CN`이 `zh_TW`보다 먼저 정의되면 `zh` → `zh_CN` 매핑
+
+4. **기본 언어 반환**: 모든 매칭이 실패하면 기본 언어(`default`) 사용
+
+##### 실제 동작 예시
+
+```
+# 브라우저 언어가 'ko,en-US'이고 URL이 기본 도메인인 경우:
+/ → /ko_KR/  (브라우저 언어 기반 리다이렉트)
+
+# 사용자가 언어 전환 후 쿠키에 'zh_CN' 저장:
+/ko_KR/about → /zh_CN/about  (다음 방문 시 쿠키 기반 리다이렉트)
+
+# 브라우저 언어가 'zh-HK'이지만 'zh_HK'가 지원되지 않고 매핑된 경우:
+/ → /zh_TW/  (특별 매핑 'zh_HK'=>'zh_TW' 적용, 중국어 홍콩/대만 차이점 참고: https://kargn.as/posts/differences-hong-kong-taiwan-chinese-website-ui-localisation)
+
+# 브라우저 언어가 지원되지 않는 'ru'인 경우:
+/ → /  (기본 언어 유지, 리다이렉트 없음)
+```
+
 #### 라우트 생성 예시
 
 ```php

config/essentials-entry.php

@@ -97,6 +97,7 @@
         // 특별 매핑 관계 (서로 대체 가능한 언어들)
         'locale_mappings' => [
             // 번체 중국어 상호 참조 (zh_HK와 zh_TW는 모두 번체 중국어라 서로 대체 가능)
+            // 중국어 홍콩/대만 버전 차이점은 https://kargn.as/posts/differences-hong-kong-taiwan-chinese-website-ui-localisation 참고
             'zh_HK' => 'zh_TW',
             'zh_TW' => 'zh_HK',
         ],