Laravel 한글 언어팩 적용하기, 유효성 검사 메시지 한글화

Laravel의 기본 유효성 검사 메시지는 영어다. The email field is required. 같은 문구가 그대로 사용자에게 노출되면 곤란하다.

가장 많이 쓰는 기본 항목만 한글화한 언어팩을 만들어서 공개해두었다.

https://github.com/yousung/laravel-lang-ko

적용 방법

방법 1: 직접 복사

저장소를 받아 언어 디렉터리에 넣으면 된다.

# Laravel 9 이상
[PROJECT_ROOT]/lang/ko/

# Laravel 8 이하
[PROJECT_ROOT]/resources/lang/ko/

방법 2: git clone

cd [PROJECT_ROOT]
git clone https://github.com/yousung/laravel-lang-ko.git resources/lang/ko

3. 기본 로케일 변경

파일만 넣는다고 적용되지 않는다. 로케일을 ko로 바꿔야 한다.

// config/app.php
'locale' => 'ko',
'fallback_locale' => 'en',   // ko에 없는 키는 영어로

# .env (Laravel 11+)
APP_LOCALE=ko
APP_FALLBACK_LOCALE=en

fallback_locale을 en으로 두는 게 중요하다. 한글 파일에 없는 키가 있어도 영어로라도 표시되기 때문이다. 이걸 ko로 두면 키 이름이 그대로 화면에 노출된다.

언어 파일 구조

Laravel의 언어 파일은 용도별로 나뉜다.

• validation.php : 유효성 검사 메시지. 실무에서 가장 중요하다
• auth.php : 로그인 실패, 인증 관련
• passwords.php : 비밀번호 재설정
• pagination.php : 이전/다음 링크

필드명까지 한글로 바꾸기

언어팩만 적용하면 이렇게 나온다.

email 항목은 필수입니다.

필드명이 영어 그대로다. validation.php의 attributes 배열에 매핑을 넣으면 해결된다.

// lang/ko/validation.php
'attributes' => [
    'email'    => '이메일',
    'password' => '비밀번호',
    'name'     => '이름',
    'mobile'   => '휴대폰 번호',
],

이러면 이메일 항목은 필수입니다. 로 나온다. 이 부분은 프로젝트마다 필드가 다르므로 언어팩이 대신해줄 수 없다. 직접 채워야 하는 영역이다.

특정 필드에만 다른 메시지

필드와 규칙 조합별로 메시지를 지정할 수도 있다.

'custom' => [
    'password' => [
        'min'       => '비밀번호는 최소 :min자 이상이어야 합니다.',
        'confirmed' => '비밀번호가 일치하지 않습니다.',
    ],
],

또는 FormRequest에서 직접 정의하는 방법도 있다.

public function messages(): array
{
    return [
        'email.required' => '이메일을 입력해 주세요.',
        'email.unique'   => '이미 가입된 이메일입니다.',
    ];
}

public function attributes(): array
{
    return ['email' => '이메일'];
}

공통 규칙은 언어 파일에, 화면별 특수 문구는 FormRequest에 두는 식으로 나누면 관리가 편하다.

다국어 서비스라면

사용자별로 언어를 바꿔야 한다면 미들웨어에서 로케일을 설정한다.

public function handle($request, Closure $next)
{
    $locale = $request->user()?->locale
        ?? $request->getPreferredLanguage(['ko', 'en', 'ja']);

    App::setLocale($locale);

    return $next($request);
}

getPreferredLanguage()는 브라우저의 Accept-Language 헤더를 읽는다. 로그인 전 사용자에게도 적절한 언어를 보여줄 수 있다.

다른 선택지

더 완전한 번역이 필요하면 Laravel-Lang/lang 프로젝트가 있다. 80개 이상 언어의 전체 문구를 관리하는 커뮤니티 프로젝트다.

composer require laravel-lang/common --dev
php artisan lang:add ko

내 언어팩은 자주 쓰는 기본 항목 위주라 가볍다는 게 장점이고, Laravel-Lang은 커버리지가 넓다는 게 장점이다. 프로젝트 성격에 맞게 고르면 된다.

정리

• 언어 파일 위치는 Laravel 9+ 부터 lang/, 이전은 resources/lang/
• 파일만 넣으면 안 되고 locale을 ko로 변경해야 한다
• fallback_locale은 en으로 두는 게 안전하다
• 필드명 한글화는 attributes 배열에 직접 채워야 한다
• 화면별 특수 문구는 FormRequest의 messages()로