다국어

번역일: 2026년 6월 20일

다국어

소개
번역 문자열 정의
- 짧은 키 사용
- 번역 문자열을 키로 사용
번역 문자열 불러오기
- 번역 문자열의 파라미터 치환
- 복수형 처리
패키지 언어 파일 오버라이딩

소개

NOTE

기본적으로 Laravel 애플리케이션 스켈레톤에는 lang 디렉토리가 포함되어 있지 않습니다. 언어 파일을 커스터마이징하려면 lang:publish Artisan 명령어로 먼저 퍼블리싱해야 합니다.

Laravel의 다국어(Localization) 기능을 사용하면 여러 언어로 문자열을 손쉽게 관리할 수 있어, 다국어를 지원하는 애플리케이션을 쉽게 만들 수 있습니다.

번역 문자열을 관리하는 방법은 두 가지입니다.

1. PHP 파일 방식: lang 디렉토리 아래에 언어별 하위 디렉토리를 만들고, 그 안에 PHP 파일로 번역 문자열을 정의합니다. Laravel의 유효성 검사 오류 메시지 등 프레임워크 내장 기능도 이 방식을 사용합니다.

/lang
    /en
        messages.php
    /ko
        messages.php

2. JSON 파일 방식: lang 디렉토리에 언어별 JSON 파일을 직접 생성합니다. 번역할 문자열이 많은 대규모 애플리케이션에 적합합니다.

/lang
    en.json
    ko.json

두 방식 모두 이 문서에서 자세히 다룹니다.

언어 파일 퍼블리싱

기본 Laravel 프로젝트에는 lang 디렉토리가 없습니다. 언어 파일을 직접 커스터마이징하거나 새로 만들고 싶다면, 다음 Artisan 명령어로 lang 디렉토리와 기본 언어 파일을 생성할 수 있습니다.

php artisan lang:publish

이 명령어를 실행하면 lang 디렉토리가 생성되고 Laravel 기본 언어 파일들이 그 안에 복사됩니다.

로케일 설정

애플리케이션의 기본 언어(로케일)는 config/app.php 파일의 locale 옵션에서 설정합니다. 이 값을 애플리케이션에 맞게 자유롭게 변경할 수 있습니다.

특정 HTTP 요청에 대해서만 런타임에 로케일을 바꾸고 싶다면, App 파사드의 setLocale 메서드를 사용합니다.

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'ko', 'ja'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

활성 언어에 해당 번역 문자열이 없을 때 사용할 **대체 언어(fallback locale)**도 config/app.php에서 설정할 수 있습니다.

'fallback_locale' => 'en',

현재 로케일 확인

현재 로케일을 확인하거나 특정 로케일인지 검사하려면 App 파사드의 currentLocale 및 isLocale 메서드를 사용합니다.

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('ko')) {
    // 현재 한국어 로케일인 경우
}

복수형 언어 설정

Laravel 내부에서 Eloquent 등 여러 곳에 사용되는 "복수형 변환기(pluralizer)"는 기본적으로 영어 규칙을 따릅니다. 다른 언어의 복수형 규칙을 사용하려면, 서비스 프로바이더의 boot 메서드에서 Pluralizer::useLanguage를 호출하면 됩니다. 현재 지원 언어는 french, norwegian-bokmal, portuguese, spanish, turkish입니다.

use Illuminate\Support\Pluralizer;

/**
 * 애플리케이션 서비스를 초기화합니다.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

WARNING

복수형 언어를 커스터마이징하면, Eloquent 모델의 테이블 이름을 명시적으로 지정해야 합니다.

번역 문자열 정의

짧은 키 사용

번역 문자열을 PHP 파일로 관리할 때는 lang 디렉토리 아래에 언어별 하위 디렉토리를 만들고 파일을 위치시킵니다.

/lang
    /en
        messages.php
    /ko
        messages.php

각 언어 파일은 키-값 쌍의 배열을 반환합니다.

<?php

// lang/ko/messages.php

return [
    'welcome' => '애플리케이션에 오신 것을 환영합니다!',
];

WARNING

지역(territory)이 다른 언어를 구분할 때는 ISO 15897 형식으로 디렉토리 이름을 지정해야 합니다. 예를 들어 영국 영어는 en-gb가 아니라 en_GB를 사용합니다.

번역 문자열을 키로 사용

번역 문자열이 많아질수록 모든 문자열에 짧은 키를 부여하는 방식은 관리하기 번거로워질 수 있습니다. 이럴 때는 원문 문자열 자체를 키로 사용하는 JSON 파일 방식이 편리합니다.

예를 들어 한국어 번역을 추가하려면 lang/ko.json 파일을 생성합니다.

{
    "I love programming.": "저는 프로그래밍을 정말 좋아합니다."
}

키와 파일명 충돌 주의

번역 키 이름이 다른 언어 파일명과 충돌하지 않도록 주의해야 합니다. 예를 들어 nl.json 파일이 없는 상태에서 nl/action.php 파일이 존재할 때 __('Action')을 호출하면, 번역기가 nl/action.php 파일 전체 내용을 반환하는 예상치 못한 동작이 발생할 수 있습니다.

번역 문자열 불러오기

번역 문자열은 __ 헬퍼 함수로 불러옵니다. 짧은 키 방식을 사용할 때는 파일명.키 형태의 "점(dot) 문법"을 사용합니다. 예를 들어 lang/ko/messages.php의 welcome 키를 가져오려면 다음과 같이 작성합니다.

echo __('messages.welcome');

해당 번역 문자열이 존재하지 않으면, __ 함수는 전달된 키 그대로(messages.welcome)를 반환합니다.

번역 문자열 자체를 키로 사용하는 방식에서는 원문 문자열을 그대로 전달합니다.

echo __('I love programming.');

마찬가지로 해당 번역이 없으면 전달한 문자열이 그대로 반환됩니다.

Blade 템플릿에서는 {{ }} 구문을 사용합니다.

{{ __('messages.welcome') }}

번역 문자열의 파라미터 치환

번역 문자열 안에 : 접두사를 붙인 플레이스홀더를 정의할 수 있습니다.

'welcome' => '환영합니다, :name님!',

__ 함수의 두 번째 인수로 치환할 값의 배열을 전달하면 플레이스홀더가 교체됩니다.

echo __('messages.welcome', ['name' => '지수']);

플레이스홀더가 모두 대문자이거나 첫 글자만 대문자인 경우, 치환된 값도 그에 맞춰 대소문자가 변환됩니다. 주로 영어 문자열에서 의미가 있습니다.

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

객체를 플레이스홀더로 사용하기

플레이스홀더에 객체를 전달하면 해당 객체의 __toString 메서드가 자동으로 호출됩니다. 그런데 서드파티 라이브러리의 클래스처럼 __toString을 직접 제어할 수 없는 경우가 있습니다.

이럴 때는 Lang 파사드의 stringable 메서드로 특정 타입에 대한 커스텀 포매팅 핸들러를 등록할 수 있습니다. 보통 AppServiceProvider의 boot 메서드에서 등록합니다.

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * 애플리케이션 서비스를 초기화합니다.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('ko_KR');
    });
}

복수형 처리

언어마다 복수형 규칙이 다르기 때문에 복수형 처리는 까다로운 문제입니다. Laravel에서는 | 문자를 사용해 단수형과 복수형 표현을 구분할 수 있습니다.

'apples' => '사과가 한 개 있습니다.|사과가 여러 개 있습니다.',

JSON 파일 방식에서도 동일하게 사용할 수 있습니다.

{
    "There is one apple|There are many apples": "사과가 한 개 있습니다.|사과가 여러 개 있습니다."
}

범위를 지정한 더 복잡한 복수형 규칙도 정의할 수 있습니다.

'apples' => '{0} 사과가 없습니다.|[1,19] 사과가 몇 개 있습니다.|[20,*] 사과가 많이 있습니다.',

복수형 옵션이 있는 번역 문자열을 불러올 때는 trans_choice 함수에 수량을 전달합니다. 아래 예시에서 수량이 10이므로 [1,19] 범위에 해당하는 문자열이 반환됩니다.

echo trans_choice('messages.apples', 10);

플레이스홀더도 함께 사용할 수 있습니다. 세 번째 인수로 치환 배열을 전달합니다.

'minutes_ago' => '{1} :value분 전|[2,*] :value분 전',

echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

trans_choice에 전달한 정수 값 자체를 표시하려면 내장 플레이스홀더 :count를 사용합니다.

'apples' => '{0} 사과가 없습니다.|{1} 사과가 한 개 있습니다.|[2,*] 사과가 :count개 있습니다.',

패키지 언어 파일 오버라이딩

일부 패키지는 자체 언어 파일을 포함하고 있습니다. 패키지의 핵심 파일을 직접 수정하는 대신, lang/vendor/{패키지}/{로케일} 디렉토리에 같은 이름의 파일을 두어 원하는 번역 문자열만 덮어쓸 수 있습니다.

예를 들어 skyrim/hearthfire 패키지의 messages.php 영어 번역 일부를 수정하려면, lang/vendor/hearthfire/en/messages.php 파일을 만들고 변경할 문자열만 정의합니다. 파일에 정의하지 않은 나머지 번역 문자열은 패키지 원본 파일에서 그대로 불러옵니다.