다국어

번역일: 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 디렉터리가 없습니다. Laravel 내장 언어 파일을 커스터마이징하거나 직접 언어 파일을 만들려면, 먼저 lang:publish 명령을 실행하여 디렉터리와 기본 언어 파일을 생성해야 합니다.

php artisan lang:publish

로케일 설정

애플리케이션의 기본 언어는 config/app.php의 locale 옵션으로 지정합니다. 보통 .env 파일의 APP_LOCALE 환경 변수로 설정합니다.

기본 언어에 해당 번역이 없을 때 사용할 폴백 언어(fallback language) 도 같은 파일에서 APP_FALLBACK_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);

    // ...
});

현재 로케일 확인

현재 설정된 로케일을 확인하거나 특정 로케일인지 검사할 때는 App 파사드의 currentLocale과 isLocale 메서드를 사용합니다.

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('ko')) {
    // ...
}

복수형 언어 설정

Laravel은 Eloquent 등 프레임워크 내부에서 단수형을 복수형으로 변환할 때 기본적으로 영어 규칙을 따릅니다. 다른 언어의 복수형 규칙을 사용하려면, 서비스 프로바이더의 boot 메서드에서 Pluralizer::useLanguage를 호출하세요. 현재 지원 언어는 french, norwegian-bokmal, portuguese, spanish, turkish입니다.

use Illuminate\Support\Pluralizer;

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

    // ...
}

WARNING

복수형 언어를 변경하면, Eloquent가 테이블 이름을 자동으로 추론하는 방식에 영향을 줍니다. 반드시 Eloquent 모델에 테이블 이름을 명시적으로 지정하세요.

번역 문자열 정의

짧은 키 사용

번역 문자열을 짧은 키로 관리하는 방법입니다. lang 디렉터리 아래에 언어별 하위 디렉터리를 만들고, 각 디렉터리 안에 PHP 파일을 배치합니다.

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

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

<?php

// lang/en/messages.php

return [
    'welcome' => 'Welcome to our application!',
];

<?php

// lang/ko/messages.php

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

WARNING

지역(territory)이 다른 같은 언어를 구분해야 할 경우(예: 영국 영어와 미국 영어), ISO 15897 형식에 따라 디렉터리명을 지정하세요. 영국 영어라면 en-gb가 아닌 en_GB를 사용해야 합니다.

번역 문자열 자체를 키로 사용

번역 문자열이 많아질수록 짧은 키 방식은 관리가 번거로울 수 있습니다. 키를 계속 발명하는 대신, 원문 문자열 자체를 키로 사용하는 JSON 파일 방식을 활용할 수 있습니다.

lang 디렉터리에 언어 코드명의 JSON 파일을 만들고, 원문을 키로, 번역문을 값으로 작성합니다. 예를 들어 한국어 번역이라면 lang/ko.json을 만듭니다.

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

키와 파일 이름 충돌 주의

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

번역 문자열 가져오기

번역 문자열은 __ 헬퍼 함수로 가져옵니다.

짧은 키 방식 — 파일명과 키를 점(.) 표기법으로 전달합니다.

echo __('messages.welcome');

원문 키 방식 — 원문 문자열을 그대로 전달합니다.

echo __('I love programming.');

해당 번역 문자열이 없으면, __ 함수는 전달받은 키 자체를 그대로 반환합니다. 즉, 번역이 누락되어도 원문이 표시되므로 개발 중에 유용합니다.

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

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

번역 문자열의 플레이스홀더 치환

번역 문자열 안에 : 로 시작하는 플레이스홀더를 정의할 수 있습니다.

'welcome' => 'Welcome, :name',

// lang/ko/messages.php
'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' => 'There is one apple|There are many apples',

JSON 키 방식에서도 마찬가지로 사용할 수 있습니다.

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

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

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

복수형 번역 문자열은 trans_choice 함수로 가져옵니다. 두 번째 인자로 개수를 전달하면, 해당 개수에 맞는 형태의 문자열이 반환됩니다.

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 파일을 만들고, 변경하고 싶은 항목만 정의하면 됩니다. 오버라이딩하지 않은 나머지 문자열은 패키지의 원본 언어 파일에서 자동으로 불러옵니다.