다국어

업데이트됨

번역일: 2026년 6월 20일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 20일

다국어

소개
번역 문자열 정의
- 단축 키 방식
- 번역 문자열을 키로 사용하는 방식
번역 문자열 조회
- 번역 문자열의 파라미터 치환
- 복수형 처리
패키지 언어 파일 오버라이드

소개

NOTE

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

Laravel의 다국어(로컬라이제이션) 기능을 사용하면 언어별로 다른 문자열을 손쉽게 관리할 수 있으며, 하나의 애플리케이션에서 여러 언어를 지원하는 것이 간단해집니다.

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

1. 언어별 PHP 파일 방식: lang 디렉터리 안에 언어 코드로 된 하위 디렉터리를 만들고 PHP 파일로 번역 문자열을 관리합니다. Laravel의 유효성 검사 오류 메시지 같은 내장 기능도 이 방식을 사용합니다.

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

2. JSON 파일 방식: 언어별로 JSON 파일 하나를 lang 디렉터리에 두는 방식입니다. 번역 문자열의 수가 많은 애플리케이션에 권장됩니다.

/lang
    en.json
    ko.json

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

언어 파일 퍼블리시

기본 스켈레톤에는 lang 디렉터리가 없으므로, 언어 파일을 커스터마이즈하거나 새로 만들려면 먼저 아래 명령어를 실행하세요. 이 명령어는 lang 디렉터리를 생성하고 Laravel 기본 언어 파일을 함께 퍼블리시합니다.

php artisan lang:publish

로케일 설정

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

기본 언어에 해당 번역 문자열이 없을 때 사용할 폴백(fallback) 언어도 config/app.php에서 설정할 수 있습니다. 환경 변수로는 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의 복수형 처리기(Pluralizer)는 Eloquent 등 프레임워크 내부에서 단수 문자열을 복수로 변환할 때 사용됩니다. 기본값은 영어이지만, 서비스 프로바이더의 boot 메서드에서 useLanguage 메서드를 호출해 언어를 변경할 수 있습니다. 현재 지원되는 언어는 french, norwegian-bokmal, portuguese, spanish, turkish입니다.

use Illuminate\Support\Pluralizer;

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

    // ...
}

WARNING

복수형 언어를 변경하면 Eloquent 모델의 테이블 이름을 명시적으로 정의해야 합니다. 자동 추론 결과가 달라질 수 있기 때문입니다.

번역 문자열 정의

단축 키 방식

번역 문자열은 lang 디렉터리 안에 언어별 하위 디렉터리를 만들고 PHP 파일로 관리합니다.

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

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

<?php

// lang/ko/messages.php

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

WARNING

지역별로 구분이 필요한 언어(예: 영국 영어와 미국 영어)는 ISO 15897 표준에 따라 디렉터리 이름을 지정하세요. 예를 들어 영국 영어는 en-gb가 아닌 en_GB로 명명해야 합니다.

번역 문자열을 키로 사용하는 방식

번역 문자열이 많은 애플리케이션에서 매번 단축 키를 만드는 작업은 번거롭고 관리가 어렵습니다. 이를 해결하기 위해 기본 언어의 문자열 자체를 키로 사용하는 방식을 제공합니다. 이 방식에서는 언어 파일을 lang 디렉터리에 JSON 형식으로 저장합니다. 예를 들어 한국어 번역이 필요하다면 lang/ko.json 파일을 만들면 됩니다.

{
    "I love programming.": "프로그래밍이 너무 좋아요."
}

키와 파일명 충돌 주의

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

번역 문자열 조회

번역 문자열을 가져올 때는 __ 헬퍼 함수를 사용합니다. 단축 키 방식을 사용하는 경우, 파일명.키 형태의 "점(dot) 문법"으로 전달합니다. 예를 들어 lang/ko/messages.php에서 welcome 키를 가져오려면 다음과 같이 작성합니다.

echo __('messages.welcome');

지정한 번역 문자열이 존재하지 않으면 __ 함수는 전달된 키를 그대로 반환합니다. 즉, 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('en_GB');
    });
}

복수형 처리

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

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

JSON 키 방식에서도 복수형 처리가 가능합니다.

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

값의 범위를 지정해 더 세밀한 규칙을 만들 수도 있습니다.

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

복수형 번역 문자열을 조회할 때는 trans_choice 함수를 사용합니다. 두 번째 인자로 전달된 수(count)에 따라 적절한 형태가 반환됩니다.

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} :count개|[2,*] :count개',

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

일부 패키지는 자체 언어 파일을 포함하고 있습니다. 패키지 코어 파일을 직접 수정하는 대신, lang/vendor/{패키지명}/{로케일} 디렉터리에 파일을 배치해 원하는 문자열만 오버라이드할 수 있습니다.

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