Localization

• Introduction
  • Publishing the Language Files
  • Configuring the Locale
  • Pluralization Language
• Defining Translation Strings
  • Using Short Keys
  • Using Translation Strings as Keys
• Retrieving Translation Strings
  • Replacing Parameters in Translation Strings
  • Pluralization
• Overriding Package Language Files

Introduction

기본적으로, Laravel 애플리케이션 골격에는 lang 디렉터리가 포함되어 있지 않습니다. Laravel의 언어 파일을 사용자화하려면 lang:publish Artisan 명령어로 해당 파일들을 배포할 수 있습니다.

Laravel의 로컬라이제이션 기능은 다양한 언어의 문자열을 편리하게 가져올 수 있는 방법을 제공하여, 애플리케이션 내에서 다국어 지원을 쉽게 할 수 있게 합니다.

Laravel은 번역 문자열을 관리하는 두 가지 방식을 제공합니다. 첫 번째는 애플리케이션의 lang 디렉터리에 파일로 저장하는 방법입니다. 이 디렉터리 내에는 애플리케이션에서 지원하는 각 언어별 하위 디렉터리가 존재할 수 있습니다. 이 방식은 Laravel에서 내장 기능(예: 유효성 검증 오류 메시지)의 번역 문자열을 관리할 때 주로 사용합니다:

/lang
    /en
        messages.php
    /es
        messages.php

또 다른 방식은 lang 디렉터리에 JSON 파일을 두고 번역 문자열을 정의하는 것입니다. 이 방법에서는 애플리케이션에서 지원하는 각 언어별로 대응하는 JSON 파일을 두게 됩니다. 번역 문자열이 많을 경우 이 방식을 권장합니다:

/lang
    en.json
    es.json

이 문서에서는 두 가지 번역 문자열 관리 방식을 차례로 설명합니다.

Publishing the Language Files

기본적으로 Laravel 애플리케이션 골격에는 lang 디렉터리가 포함되어 있지 않습니다. Laravel 언어 파일을 사용자화하거나 직접 생성하려면 lang:publish Artisan 명령어로 lang 디렉터리를 스캐폴딩하는 것이 좋습니다. lang:publish 명령어는 애플리케이션에 lang 디렉터리를 생성하고 Laravel에서 사용하는 기본 언어 파일 세트를 배포합니다:

php artisan lang:publish

Configuring the Locale

애플리케이션의 기본 언어는 보통 config/app.php 설정 파일 내 locale 옵션에 저장되며, 이는 일반적으로 APP_LOCALE 환경 변수를 통해 설정됩니다. 필요에 따라 이 값을 자유롭게 변경할 수 있습니다.

또한, 기본 언어에 해당 번역이 없을 때 사용할 "대체 언어"도 설정할 수 있습니다. 대체 언어 역시 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', 'es', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

Determining the Current Locale

현재 로케일을 확인하거나 특정 로케일인지 확인할 때는 App 파사드의 currentLocale 및 isLocale 메서드를 사용할 수 있습니다:

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

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

Pluralization Language

Eloquent와 프레임워크 일부에서 단수형 문자열을 복수형으로 변환하는 데 사용하는 Laravel의 "pluralizer"에 영어 외 다른 언어를 사용하도록 지시할 수 있습니다. 이 작업은 애플리케이션의 서비스 프로바이더 중 하나의 boot 메서드 내에서 useLanguage 메서드를 호출하면 됩니다. 현재 pluralizer가 지원하는 언어는 french(프랑스어), norwegian-bokmal(노르웨이어), portuguese(포르투갈어), spanish(스페인어), turkish(터키어)입니다.

use Illuminate\Support\Pluralizer;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

pluralizer의 언어를 변경하는 경우, 반드시 Eloquent 모델의 table names을 명시적으로 정의해야 합니다.

Defining Translation Strings

Using Short Keys

일반적으로 번역 문자열은 lang 디렉터리 내 파일에 저장합니다. 이 디렉터리 내부에는 애플리케이션에서 지원하는 각 언어별 하위 디렉터리가 있어야 합니다. 이 방식은 Laravel의 내장 기능(예: 유효성 검증 메시지) 번역 문자열 관리에 사용됩니다:

/lang
    /en
        messages.php
    /es
        messages.php

모든 언어 파일은 키-값 형태의 배열을 반환합니다. 예시:

<?php

// lang/en/messages.php

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

지명이나 국가는 ISO 15897 표준에 따라 언어 디렉터리를 명명해야 합니다. 예를 들어 영국 영어는 "en_GB"로, "en-gb"가 아닙니다.

Using Translation Strings as Keys

번역 가능한 문자열이 많은 애플리케이션에서는 모든 문자열을 "짧은 키"로 정의하면 뷰에서 키를 참조할 때 혼란스러워질 수 있고, 지원하는 모든 번역 문자열마다 키를 계속 새로 만들어 내는 것도 번거롭습니다.

이러한 이유로 Laravel은 문자열의 "기본" 번역 자체를 키로 사용해 번역 문자열을 정의하는 방식도 지원합니다. 번역 문자열을 키로 사용하는 언어 파일은 lang 디렉터리에 JSON 파일로 저장합니다. 예를 들어 애플리케이션이 스페인어 번역을 지원한다면 lang/es.json 파일을 만들어야 합니다:

{
    "I love programming.": "Me encanta programar."
}

Key / File Conflicts

다른 번역 파일명과 충돌하는 키를 정의해서는 안 됩니다. 예를 들어 __('Action')을 "NL" 로케일에서 번역하려 할 때 nl/action.php 파일이 존재하고 nl.json 파일은 없으면, 해당 번역자는 nl/action.php 파일 전체를 반환하게 됩니다.

Retrieving Translation Strings

__ 헬퍼 함수를 이용해 언어 파일에서 번역 문자열을 가져올 수 있습니다. 짧은 키 방식을 사용할 경우, 키가 포함된 파일과 키 자체를 "dot"(닷) 구문으로 __ 함수에 전달합니다. 예를 들어 lang/en/messages.php 파일 내 welcome 키 값을 가져올 때:

echo __('messages.welcome');

만약 지정한 번역 문자열이 없으면 __ 함수는 번역 문자열 키를 반환합니다. 따라서 위 예시에서 해당 번역 문자열이 없으면 __ 함수는 messages.welcome을 반환합니다.

default translation strings as your translation keys을 쓸 경우에는 __ 함수에 해당 문자열의 기본 번역문을 그대로 넘깁니다:

echo __('I love programming.');

이 경우에도 번역 문자열이 없으면 __ 함수는 전달받은 번역 문자열 키를 그대로 반환합니다.

Blade templating engine을 사용하는 경우, {{ }} 출력 구문을 활용할 수 있습니다:

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

Replacing Parameters in Translation Strings

필요한 경우 번역 문자열 내에 플레이스홀더(자리표시자)를 정의할 수 있습니다. 모든 플레이스홀더는 :로 시작합니다. 예를 들어 이름을 넣는 환영 메시지를 정의할 수 있습니다:

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

번역 문자열을 가져올 때 치환할 값은 __ 함수의 두 번째 인자로 배열 형태로 전달합니다:

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

플레이스홀더가 전부 대문자거나 첫 글자만 대문자일 경우, 치환된 값도 대응되는 형식으로 자동 변환됩니다:

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

Object Replacement Formatting

번역 문자열 플레이스홀더에 객체를 사용할 경우, 해당 객체의 __toString 메서드가 호출됩니다. __toString 메서드는 PHP의 내장 "매직 메서드" 중 하나입니다. 그러나 간혹 서드파티 라이브러리 클래스 등, __toString 메서드를 직접 제어하기 어려운 경우도 있습니다.

이때 Laravel에서는 특정 객체 유형에 대해 커스텀 포맷팅 핸들러를 등록할 수 있습니다. 이를 위해 번역자(translator)의 stringable 메서드를 호출하면 됩니다. stringable 메서드는 클로저를 받으며, 이 클로저는 포맷팅을 책임질 객체 타입을 타입힌트로 명시해야 합니다. 보통 stringable 메서드는 애플리케이션 AppServiceProvider 클래스의 boot 메서드 내에서 호출합니다:

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

Pluralization

복수형 처리는 언어마다 다양한 복잡한 규칙이 있으므로 까다로운 문제이지만, Laravel은 사용자가 정의한 복수형 규칙에 따라 다르게 번역할 수 있게 도와줍니다. | 문자로 단수형과 복수형 구분이 가능합니다:

'apples' => 'There is one apple|There are many apples',

물론 translation strings as keys에서도 복수형을 지원합니다:

{
    "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}

더욱 복잡한 복수형 규칙도 만들 수 있습니다. 예를 들어, 여러 개수 구간별 메시지를 지정할 수 있습니다:

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

복수형 옵션이 포함된 번역 문자열을 정의한 뒤에는 trans_choice 함수를 사용해 주어진 "개수"에 맞는 문장 형태를 가져옵니다. 아래 예에서는 1보다 크므로 복수형 번역 문자열이 반환됩니다:

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

복수형 문자열 안에 플레이스홀더도 정의할 수 있으며, 이는 trans_choice 함수의 세 번째 인자로 배열로 전달해 치환할 수 있습니다:

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

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

trans_choice 함수에 전달한 정수 값을 표시하고 싶을 때는 내장 플레이스홀더인 :count를 사용할 수 있습니다:

'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',

Overriding Package Language Files

일부 패키지는 자체 언어 파일을 포함하여 배포합니다. 패키지 코어 파일을 직접 수정하는 대신, lang/vendor/{package}/{locale} 디렉터리에 파일을 두어 번역 문자열을 덮어쓸 수 있습니다.

예를 들어 skyrim/hearthfire라는 패키지의 영어 messages.php 번역 문자열을 덮어쓰려면, lang/vendor/hearthfire/en/messages.php 경로에 파일을 두면 됩니다. 이 파일에는 덮어쓸 번역 문자열만 정의하면 되며, 수정하지 않은 문자열은 원래 패키지 언어 파일에서 계속 로드됩니다.