본문 바로가기

다국어

번역일: 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 디렉터리를 생성하고 기본 언어 파일을 배포하세요.

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 모델의 테이블 이름을 명시적으로 지정해야 합니다.

번역 문자열 정의

짧은 키 사용

번역 문자열을 PHP 파일로 관리할 때는 lang 디렉터리 아래에 언어별 하위 디렉터리를 만들고, 그 안에 PHP 파일을 둡니다. 각 파일은 키-값 배열을 반환합니다.

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

예시:

<?php // lang/ko/messages.php return [ 'welcome' => '애플리케이션에 오신 것을 환영합니다!', ];

WARNING

지역(territory)이 다른 언어를 구분할 때는 ISO 15897 표준에 따라 디렉터리 이름을 지정하세요. 예를 들어 영국 영어는 en-gb가 아닌 en_GB를 사용해야 합니다.

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

번역할 문자열이 많아지면 짧은 키를 일일이 만들고 관리하는 것이 번거로울 수 있습니다. 이런 경우 원문 문자열 자체를 키로 사용하는 JSON 방식을 활용하면 편리합니다.

JSON 파일은 lang 디렉터리에 언어 코드를 파일명으로 저장합니다. 예를 들어 한국어 번역 파일은 lang/ko.json으로 생성합니다.

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

키와 파일명 충돌 주의

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

번역 문자열 조회

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

짧은 키 방식을 사용하는 경우 파일명.키 형태의 점(dot) 표기법을 사용합니다.

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 함수로 조회합니다. 두 번째 인자로 숫자를 전달하면 해당 숫자에 맞는 형태가 반환됩니다.

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 파일을 만들면 됩니다. 이 파일에는 재정의할 문자열만 정의하면 되고, 나머지 문자열은 패키지 원본 언어 파일에서 그대로 불러옵니다.

이 문서는 Laravel 공식 문서(MIT)를 한국 개발자를 위해 번역·재구성한 것입니다.

번역일: 2026년 6월 20일