지역화 (다국어)

• 시작하기
  • Locale 설정하기
  • 복수화 언어
• 다국어 문자값 정의하기
  • 짧은 키 사용하기
  • 다국어 문자열을 키로 사용하기
• 다국어 문자 조회하기
  • 다국어 문자열의 파라미터를 치환하기
  • 복수 표기
• 패키지의 언어 파일 재정의하기

시작하기

라라벨의 현지화 기능은 다양한 언어로 된 문자열을 검색하는 편리한 방법을 제공하므로 애플리케이션 내에서 여러 언어를 쉽게 지원할 수 있습니다.

라라벨은 번역 문자열을 관리하는 두 가지 방법을 제공합니다. 첫째, 언어 문자열은 lang 디렉토리 내의 파일에 저장할 수 있습니다. 이 디렉토리에는 애플리케이션에서 지원하는 각 언어에 대한 하위 디렉토리가 있을 수 있습니다. 이것은 라라벨이 유효성 검사 오류 메시지와 같은 내장 라라벨 기능에 대한 번역 문자열을 관리하는 데 사용하는 접근 방식입니다.

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

또는 lang 디렉토리에 있는 JSON 파일 내에 번역 문자열을 정의할 수 있습니다. 이 접근 방식을 사용할 때 애플리케이션에서 지원하는 각 언어는 이 디렉토리 내에 해당 JSON 파일을 갖습니다. 이 접근 방식은 번역 가능한 문자열이 많은 애플리케이션에 권장됩니다.

/lang
    en.json
    es.json

이 문서에서 번역 문자열을 관리하는 각 접근 방식에 대해 설명합니다.

로케일 설정하기

애플리케이션의 기본 언어는 config/app.php 설정 파일의 locale 설정 옵션에 저장됩니다. 애플리케이션의 요구 사항에 맞게 이 값을 자유롭게 수정할 수 있습니다.

App 파사드에서 제공하는 setLocale 메소드를 사용하여 런타임 시 단일 HTTP 요청에 대한 기본 언어를 수정할 수 있습니다.

use Illuminate\Support\Facades\App;

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

    App::setLocale($locale);

    //
});

지정된 언어로 설정된 문자열이 존재하지 않는 경우에 사용할 수 있는 "대체 언어"를 설정 할 수 있습니다. 기본언어와 마찬가지로 대체 언어는 config/app.php 설정 파일에서 지정할 수 있습니다.

'fallback_locale' => 'en',

현재 로케일 확인하기

App 파사드에서 currentLocale 및 isLocale 메소드를 사용하여 현재 로케일을 결정하거나 로케일이 주어진 값인지 확인할 수 있습니다.

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

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

Pluralization Language

복수화 언어

Eloquent 및 프레임워크의 다른 부분에서 단수 문자열을 복수 문자열로 변환하는 데 사용하는 라라벨의 "pluralizer"에 영어 이외의 언어를 사용하도록 지시할 수 있습니다. 이것은 애플리케이션의 서비스 공급자 중 하나의 boot 메서드 내에서 useLanguage 메서드를 호출하여 수행할 수 있습니다 . pluralizer가 현재 지원하는 언어는 프랑스어, norwegian-bokmal, 포르투갈어, 스페인어, 터키어 입니다.

use Illuminate\Support\Pluralizer;

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

    // ...     
}

Warning 복수형 언어를 사용자 정의하는 경우 Eloquent 모델의 테이블 이름을 명시적으로 정의해야 합니다 .

다국어 문자값 정의하기

짧은 키 사용하기

일반적으로 번역 문자열은 lang 디렉토리 내의 파일에 저장됩니다. 이 디렉토리에는 애플리케이션에서 지원하는 각 언어에 대한 하위 디렉토리가 있어야 합니다. 이것은 라라벨이 유효성 검사 오류 메시지와 같은 내장 라라벨 기능에 대한 번역 문자열을 관리하는 데 사용하는 접근 방식입니다.

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

모든 언어파일은 문자키 형태의 배열을 반환합니다. 예를 들면:

<?php

// lang/en/messages.php

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

{note} 지역별로 다른 언어의 경우 ISO 15897에 따라 언어 디렉토리의 이름을 지정해야 합니다. 예를 들어 영국식 영어의 경우 "en-gb"가 아닌 "en_GB"를 사용해야 합니다.

다국어 문자열을 키로 사용하기

번역 가능한 문자열이 많은 애플리케이션의 경우, 뷰에서 키를 참조할 때 "짧은 키"로 모든 문자열을 정의하는 것이 혼란스러울 수 있으며, 애플리케이션에서 지원하는 모든 번역 문자열에 대해 키를 계속해서 생성하는 것은 번거롭습니다.

이러한 이유로 라라벨은 문자열의 "기본" 번역을 키로 사용하여 번역 문자열 정의에 대한 지원도 제공합니다. 번역 문자열을 키로 사용하는 번역 파일은 lang 디렉토리에 JSON 파일로 저장됩니다. 예를 들어 애플리케이션에 스페인어 번역이 있는 경우 lang/es.json 파일을 만들어야 합니다.

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

키 / 파일 충돌

다른 번역 파일 이름과 충돌하는 번역 문자열 키를 정의하면 안 됩니다. 예를 들어, nl/action.php 파일이 존재하지만 nl.json 파일이 존재하지 않는 경우, "NL" 로케일에 대해 __('Action')을 번역하면 번역기가 nl/action.php의 내용을 반환하게 됩니다..

다국어 문자 조회하기

__ 헬퍼 함수를 사용하여 언어 파일에서 번역 문자열을 검색할 수 있습니다. "짧은 키"를 사용하여 번역 문자열을 정의하는 경우 "." 구문을 사용하여 키와 키 자체를 포함하는 파일을 __ 함수에 전달해야 합니다. 예를 들어 lang/en/messages.php 언어 파일에서 welcome 번역 문자열을 검색해 보겠습니다.

echo __('messages.welcome');

지정된 번역 문자열이 존재하지 않으면 __ 함수는 번역 문자열 키를 반환합니다. 따라서 위의 예를 사용하면 __ 함수는 번역 문자열이 존재하지 않는 경우 messages.welcome을 반환합니다.

기본 번역 문자열을 번역 키로 사용을 사용하는 경우 문자열의 기본 번역을 __ 함수에 전달해야 합니다.

echo __('I love programming.');

다시 말하지만, 번역 문자열이 존재하지 않으면 __ 함수는 제공된 번역 문자열 키를 반환합니다.

Blade 템플릿 엔진을 사용하는 경우 {{ }} 에코 구문을 사용하여 번역 문자열을 표시할 수 있습니다.

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

다국어 문자열의 파라미터를 치환하기

여러분은 다국어 문자에서 일부분을 특정하여 교체하기를(placeholders) 원할 수도 있습니다. 이런 모든 플레이스홀더 들은 : 으로 시작합니다. 예를들어 환영 메세지에 이름을 특정하게 표현하기를 원한다면 다음과 같이 하면 됩니다.

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

번역 문자열을 검색할 때 자리 표시자를 교체하려면 대체 할 문자의 배열을 __ 함수의 두 번째 인수로 전달할 수 있습니다.

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

플레이스 홀더가 모두 대문자이거나, 첫번째 문자가 대문자라면, 변환된 값또한 이에 따라 대문자로 표기될것 입니다.

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

객체 교체 포맷팅

번역을 위한 플레이스 홀더에 객체를 지정하면, 이 객체가 표시될 때 객체의 __toString 메서드가 호출됩니다. __toString메서드는 PHP에 내장된 "매직 메서드"입니다. 그렇지만 사용하고자 하는 클래스가 써드파티 라이브러리에 속해있는 경우와 같이 저징된 클래스에 메서드를 제어할 수 없는 경우도 있습니다.

이런 경우를 위해서 라라벨은 특정 유형의 객체를 위한 커스텀 포맷 핸들러를 등록할 수 있습니다. 이 핸들러를 등록하려면 Translator 의 stringable 메서드를 호출하면 됩니다. stringable 메서드는 클로저를 인자로 전달 받는데, 이 클로저는 포맷팅을 위한 응답 가능 객체 타입으로 힌트된 인자를 받아야 합니다. 일반적으로 이 stringable 메서드는 AppServiceProvider클래스의 boot 메서드 안에서 호출됩니다.

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

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

복수 표기

언어마다 복수화에 대한 다양한 복잡한 규칙이 있기 때문에 복수화는 복잡한 문제입니다. 그러나 라라벨은 정의한 복수화 규칙에 따라 문자열을 다르게 번역하는 데 도움을 줄 수 있습니다. | 문자를 사용하여 문자열의 단수형과 복수형을 구별할 수 있습니다.

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

물론 번역 문자열을 키로 사용을 사용할 때도 복수화가 지원됩니다.

{
  "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 함수를 사용하여 주어진 "개수"에 맞는 다국어 메세지를 표시할 수 있습니다. 예를 들어 하나 이상의 수량을 표시하는 경우에는 다음처럼 하면 됩니다.

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',

패키지의 언어 파일 재정의하기

몇몇 패키지들은 고유한 언어 파일들을 제공합니다. 출력되는 문구를 수정하기 위해 패키지의 소스를 수정하는 대신에 lang/vendor/{locale}/{package} 디렉토리에 파일을 추가하여 다국어를 재정의 할 수 있습니다.

예를 들어, skyrim/hearthfire 패키지의 영어 다국어 문자열을 대체 할 필요가 있다면, lang/vendor/en/hearthfire/en/messages.php에 언어 파일을 추가해야 합니다. 이 파일에서 여러분이 재정의하고자 하는 다국어 문자를 지정해야 합니다. 재정의하지 않은 다국어 메세지들은 패키지의 언어 파일의 정의를 그대로 따릅니다.

Localization

• Introduction
  • 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's localization features provide a convenient way to retrieve strings in various languages, allowing you to easily support multiple languages within your application.

Laravel provides two ways to manage translation strings. First, language strings may be stored in files within the lang directory. Within this directory, there may be subdirectories for each language supported by the application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:

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

Or, translation strings may be defined within JSON files that are placed within the lang directory. When taking this approach, each language supported by your application would have a corresponding JSON file within this directory. This approach is recommended for applications that have a large number of translatable strings:

/lang
    en.json
    es.json

We'll discuss each approach to managing translation strings within this documentation.

Configuring The Locale

The default language for your application is stored in the config/app.php configuration file's locale configuration option. You are free to modify this value to suit the needs of your application.

You may modify the default language for a single HTTP request at runtime using the setLocale method provided by the App facade:

use Illuminate\Support\Facades\App;

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

    App::setLocale($locale);

    //
});

You may configure a "fallback language", which will be used when the active language does not contain a given translation string. Like the default language, the fallback language is also configured in the config/app.php configuration file:

'fallback_locale' => 'en',

Determining The Current Locale

You may use the currentLocale and isLocale methods on the App facade to determine the current locale or check if the locale is a given value:

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

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

Pluralization Language

You may instruct Laravel's "pluralizer", which is used by Eloquent and other portions of the framework to convert singular strings to plural strings, to use a language other than English. This may be accomplished by invoking the useLanguage method within the boot method of one of your application's service providers. The pluralizer's currently supported languages are: french, norwegian-bokmal, portuguese, spanish, and turkish:

use Illuminate\Support\Pluralizer;

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

    // ...     
}

Warning
If you customize the pluralizer's language, you should explicitly define your Eloquent model's table names.

Defining Translation Strings

Using Short Keys

Typically, translation strings are stored in files within the lang directory. Within this directory, there should be a subdirectory for each language supported by your application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:

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

All language files return an array of keyed strings. For example:

<?php

// lang/en/messages.php

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

Warning
For languages that differ by territory, you should name the language directories according to the ISO 15897. For example, "en_GB" should be used for British English rather than "en-gb".

Using Translation Strings As Keys

For applications with a large number of translatable strings, defining every string with a "short key" can become confusing when referencing the keys in your views and it is cumbersome to continually invent keys for every translation string supported by your application.

For this reason, Laravel also provides support for defining translation strings using the "default" translation of the string as the key. Translation files that use translation strings as keys are stored as JSON files in the lang directory. For example, if your application has a Spanish translation, you should create a lang/es.json file:

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

Key / File Conflicts

You should not define translation string keys that conflict with other translation filenames. For example, translating __('Action') for the "NL" locale while a nl/action.php file exists but a nl.json file does not exist will result in the translator returning the contents of nl/action.php.

Retrieving Translation Strings

You may retrieve translation strings from your language files using the __ helper function. If you are using "short keys" to define your translation strings, you should pass the file that contains the key and the key itself to the __ function using "dot" syntax. For example, let's retrieve the welcome translation string from the lang/en/messages.php language file:

echo __('messages.welcome');

If the specified translation string does not exist, the __ function will return the translation string key. So, using the example above, the __ function would return messages.welcome if the translation string does not exist.

If you are using your default translation strings as your translation keys, you should pass the default translation of your string to the __ function;

echo __('I love programming.');

Again, if the translation string does not exist, the __ function will return the translation string key that it was given.

If you are using the Blade templating engine, you may use the {{ }} echo syntax to display the translation string:

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

Replacing Parameters In Translation Strings

If you wish, you may define placeholders in your translation strings. All placeholders are prefixed with a :. For example, you may define a welcome message with a placeholder name:

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

To replace the placeholders when retrieving a translation string, you may pass an array of replacements as the second argument to the __ function:

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

If your placeholder contains all capital letters, or only has its first letter capitalized, the translated value will be capitalized accordingly:

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

Object Replacement Formatting

If you attempt to provide an object as a translation placeholder, the object's __toString method will be invoked. The __toString method is one of PHP's built-in "magic methods". However, sometimes you may not have control over the __toString method of a given class, such as when the class that you are interacting with belongs to a third-party library.

In these cases, Laravel allows you to register a custom formatting handler for that particular type of object. To accomplish this, you should invoke the translator's stringable method. The stringable method accepts a closure, which should type-hint the type of object that it is responsible for formatting. Typically, the stringable method should be invoked within the boot method of your application's AppServiceProvider class:

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

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

Pluralization

Pluralization is a complex problem, as different languages have a variety of complex rules for pluralization; however, Laravel can help you translate strings differently based on pluralization rules that you define. Using a | character, you may distinguish singular and plural forms of a string:

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

Of course, pluralization is also supported when using translation strings as keys:

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

You may even create more complex pluralization rules which specify translation strings for multiple ranges of values:

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

After defining a translation string that has pluralization options, you may use the trans_choice function to retrieve the line for a given "count". In this example, since the count is greater than one, the plural form of the translation string is returned:

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

You may also define placeholder attributes in pluralization strings. These placeholders may be replaced by passing an array as the third argument to the trans_choice function:

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

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

If you would like to display the integer value that was passed to the trans_choice function, you may use the built-in :count placeholder:

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

Overriding Package Language Files

Some packages may ship with their own language files. Instead of changing the package's core files to tweak these lines, you may override them by placing files in the lang/vendor/{package}/{locale} directory.

So, for example, if you need to override the English translation strings in messages.php for a package named skyrim/hearthfire, you should place a language file at: lang/vendor/hearthfire/en/messages.php. Within this file, you should only define the translation strings you wish to override. Any translation strings you don't override will still be loaded from the package's original language files.