laravel localization

라라벨 현지화

Laravel 지역화 클래스와 결합하는 유용한 도구인 Laravel을 위한 쉬운 i18n 지역화입니다.

패키지는 다음을 제공합니다:

• 브라우저에서 언어 감지
• 스마트 리디렉션(세션/쿠키에 로케일 저장)
• 스마트 라우팅(사용하는 언어 수에 관계없이 경로를 한 번만 정의하세요)
• 번역 가능한 경로
• 캐싱 및 테스트 지원
• URL에서 기본 로케일을 숨기는 옵션
• 많은 스니펫 및 도우미(예: 언어 선택기)

목차

• 설치
• 용법
• 미들웨어 리디렉션
• 도우미
• 번역된 경로
• 캐싱 경로
• 테스트
• 일반적인 문제
  • POST가 작동하지 않습니다
  • MethodNotAllowedHttpException
  • 유효성 검사 메시지는 항상 기본 로캘에 있습니다.
• 협력자
• 변경 내역
• 특허

라라벨 호환성

라라벨	laravel-현지화
4.0.x	0.13.x
4.1.x	0.13.x
4.2.x	0.15.x
5.0.x/5.1.x	1.0.x
5.2.x-5.4.x(PHP 7은 필요하지 않음)	1.2.
5.2.0-6.x(PHP 버전 >= 7 필요)	1.4.x
6.x-10.x(PHP 버전 >= 7 필요)	1.8.x
10.x-11.x(PHP 버전 >= 8.2 필요)	2.0.x

설치

작곡가를 통해 패키지 설치: composer require mcamara/laravel-localization

Laravel 5.4 이하 버전에서는 서비스 제공자 등록이 필요합니다.

구성 파일

기본 구성을 편집하려면 다음을 실행할 수 있습니다.

 php artisan vendor:publish --provider="McamaraLaravelLocalizationLaravelLocalizationServiceProvider"

그 후 config/laravellocalization.php 생성됩니다.

구성 옵션은 다음과 같습니다.

• supportLocales 앱의 언어(기본값: 영어 및 스페인어).
• useAcceptLanguageHeader true인 경우 브라우저에서 자동으로 언어를 감지합니다.
• hideDefaultLocaleInURL true인 경우 URL에 기본 로케일을 표시하지 않습니다.
• localesOrder 언어를 사용자 정의 순서로 정렬합니다.
• localesMapping URL 로케일의 이름을 바꿉니다.
• utf8suffix CentOS 등의 utf8suffix 변경을 허용합니다.
• urlsIgnored 특정 URL을 무시합니다.

미들웨어 등록

app/Http/Kernel.php 파일에 패키지 미들웨어를 등록할 수 있습니다:

 <?php namespace App  Http ;

use Illuminate  Foundation  Http  Kernel as HttpKernel ;

class Kernel extends HttpKernel {
    /**
    * The application's route middleware.
    *
    * @var array
    */
    protected $ middlewareAliases = [
        /**** OTHER MIDDLEWARE ****/
        ' localize '                =>  Mcamara  LaravelLocalization  Middleware LaravelLocalizationRoutes::class,
        ' localizationRedirect '    =>  Mcamara  LaravelLocalization  Middleware LaravelLocalizationRedirectFilter::class,
        ' localeSessionRedirect '   =>  Mcamara  LaravelLocalization  Middleware LocaleSessionRedirect::class,
        ' localeCookieRedirect '    =>  Mcamara  LaravelLocalization  Middleware LocaleCookieRedirect::class,
        ' localeViewPath '          =>  Mcamara  LaravelLocalization  Middleware LaravelLocalizationViewPath::class
    ];
}

Laravel 11을 사용하는 경우 bootstrap/app.php 파일에 Closure withMiddleware 등록할 수 있습니다.

 return Application:: configure (basePath: dirname ( __DIR__ ))
    // Other application configurations
    -> withMiddleware ( function ( Middleware $ middleware ) {
        $ middleware -> alias ([
            /**** OTHER MIDDLEWARE ALIASES ****/
            ' localize '                =>  Mcamara  LaravelLocalization  Middleware LaravelLocalizationRoutes::class,
            ' localizationRedirect '    =>  Mcamara  LaravelLocalization  Middleware LaravelLocalizationRedirectFilter::class,
            ' localeSessionRedirect '   =>  Mcamara  LaravelLocalization  Middleware LocaleSessionRedirect::class,
            ' localeCookieRedirect '    =>  Mcamara  LaravelLocalization  Middleware LocaleCookieRedirect::class,
            ' localeViewPath '          =>  Mcamara  LaravelLocalization  Middleware LaravelLocalizationViewPath::class,
        ]);
    })

용법

경로 파일에 다음을 추가합니다.

 // routes/web.php

Route:: group ([ ' prefix ' => LaravelLocalization:: setLocale ()], function ()
{
	/** ADD ALL LOCALIZED ROUTES INSIDE THIS GROUP **/
	Route:: get ( ' / ' , function ()
	{
		return View:: make ( ' hello ' );
	});

	Route:: get ( ' test ' , function (){
		return View:: make ( ' test ' );
	});
});

/** OTHER PAGES THAT SHOULD NOT BE LOCALIZED **/

이 경로 그룹이 경로 파일에 추가되면 사용자는 supportedLocales Locales(기본적으로 en 및 es )에 추가된 모든 로케일에 액세스할 수 있습니다. 예를 들어 위 경로 파일은 다음 주소를 생성합니다.

 // Set application language to English
http://url-to-laravel/en
http://url-to-laravel/en/test

// Set application language to Spanish
http://url-to-laravel/es
http://url-to-laravel/es/test

// Set application language to English or Spanish (depending on browsers default locales)
// if nothing found set to default locale
http://url-to-laravel
http://url-to-laravel/test

패키지는 URL에 따라 애플리케이션 로케일 App::getLocale() 설정합니다. 그런 다음 해당 로케일은 Laravel의 지역화 기능에 사용될 수 있습니다.

다음과 같이 그룹에 미들웨어를 추가할 수 있습니다.

Route:: group (
[
	' prefix ' => LaravelLocalization:: setLocale (),
	' middleware ' => [ ' localeSessionRedirect ' , ' localizationRedirect ' , ' localeViewPath ' ]
], function (){ //...
});

권장사항

1. : 리디렉션 미들웨어를 사용하는 것이 좋습니다 . 로케일이 없는 URL은 브라우저/기본 로케일을 결정하고 현지화된 URL로 리디렉션하는 데에만 사용해야 합니다. 그렇지 않으면 검색 엔진 로봇이 http://url-to-laravel/test 와 같이 크롤링할 때 방문할 때마다 다른 언어 콘텐츠를 얻을 수 있습니다. 또한 동일한 콘텐츠에 대해 여러 개의 URL이 있으면 SEO 중복 콘텐츠 문제가 발생합니다.

2. : 리디렉션 미들웨어를 사용하더라도 링크를 현지화하는 것이 좋습니다 . 그렇지 않으면 사용자가 링크를 클릭할 때마다 최소한 한 번의 리디렉션이 발생하게 됩니다. 또한 게시물 양식의 모든 작업 URL은 가져오기 요청으로 리디렉션되는 것을 방지하기 위해 현지화되어야 합니다.

미들웨어 리디렉션

다음 리디렉션 미들웨어는 config/laravellocalization.php 의 hideDefaultLocaleInURL 및 useAcceptLanguageHeader 설정에 따라 달라집니다.

로케일세션리디렉션

URL에 로케일이 존재할 때마다 이 미들웨어에 의해 세션에 저장됩니다.

URL에 로케일이 없으면 이 미들웨어는 다음을 확인합니다.

• 세션에 저장된 로캘이 없고 useAcceptLanguageHeader true로 설정된 경우 브라우저에서 로캘을 계산하고 로캘이 포함된 URL로 리디렉션됩니다.
• 로캘이 세션에 저장되면 기본 로캘과 hideDefaultLocaleInURL 이 true로 설정되지 않은 한 로캘이 포함된 URL로 리디렉션됩니다.

예를 들어, 사용자가 http://url-to-laravel/test로 이동하고 en 현재 로케일인 경우 자동으로 http://url-to-laravel/en/test로 리디렉션됩니다.

로케일쿠키리디렉션

LocaleSessionRedirect와 유사하지만 세션 대신 쿠키에 값을 저장합니다.

URL에 로케일이 존재할 때마다 이 미들웨어에 의해 쿠키에 저장됩니다.

URL에 로케일이 없으면 이 미들웨어는 다음을 확인합니다.

• 쿠키에 로캘이 저장되지 않고 useAcceptLanguageHeader true로 설정된 경우 브라우저에서 로캘을 계산하고 로캘이 포함된 URL로 리디렉션됩니다.
• 로캘이 쿠키에 저장되면 기본 로캘과 hideDefaultLocaleInURL 이 true로 설정되지 않은 한 로캘이 포함된 URL로 리디렉션됩니다.

예를 들어, 사용자가 http://url-to-laravel/test로 이동하고 de 현재 로케일인 경우 자동으로 http://url-to-laravel/de/test로 리디렉션됩니다.

Laravel현지화RedirectFilter

기본 로캘이 URL에 있고 hideDefaultLocaleInURL 이 true로 설정된 경우 미들웨어는 로캘 없이 URL로 리디렉션됩니다.

예를 들어, es 기본 로케일인 경우 http://url-to-laravel/es/test는 http://url-to-laravel/test로 리디렉션되고 App::getLocale() 설정됩니다. es .

도우미

이 패키지에는 많은 도우미가 함께 제공됩니다.

현지화된 URL

지역화된 경로를 생성할 때 경로 모델 바인딩과 hideDefaultLocaleInURL 및 번역된 경로 설정을 고려한 지역화된 URL입니다.

현지화된 URL 가져오기

    // If current locale is Spanish, it returns `/es/test`
    <a href="{{ LaravelLocalization:: localizeUrl ( ' /test ' ) }}">@ lang ( ' Follow this link ' )</a>

특정 로케일에 대한 현지화된 URL 가져오기

특정 로캘의 현재 URL을 가져옵니다.

 // Returns current url with English locale.
{{ LaravelLocalization:: getLocalizedURL ( ' en ' ) }}

깨끗한 경로 얻기

현지화되지 않은 URL을 반환합니다.

 // Returns /about
{{ LaravelLocalization:: getNonLocalizedURL ( ' /es/about ' ) }}

특정 번역 키에 대한 URL 가져오기

원하는 로케일로 지역화된 경로를 반환합니다. 주어진 로캘에 번역 키가 없으면 이 함수는 false를 반환합니다.

 // Returns /es/acerca
{{ LaravelLocalization:: getURLFromRouteNameTranslated ( ' es ' , ' routes.about ' ) }}

속성이 있는 경로를 사용하는 현지화된 링크의 예

 // An array of attributes can be provided.
// Returns /en/archive/ghosts, /fr/archive/fantômes, /pt/arquivo/fantasmas, etc.
<a href="{{ LaravelLocalization:: getURLFromRouteNameTranslated ( App:: currentLocale (), ' routes.archive ' , array ( ' category ' => ' ghosts ' )) }}">Ghost Stories</a>

지원되는 로케일 얻기

지원되는 모든 로캘과 해당 속성을 배열로 반환합니다.

{{ LaravelLocalization:: getSupportedLocales () }}

지원되는 로케일 맞춤 주문 받기

지원되는 모든 로케일을 구성 파일에 지정된 순서대로 반환합니다. 이 기능을 사용하여 언어 선택기에서 로케일을 인쇄할 수 있습니다.

{{ LaravelLocalization:: getLocalesOrder () }}

지원되는 로캘 키 가져오기

지원되는 로케일에 대한 모든 키가 포함된 배열을 반환합니다.

{{ LaravelLocalization:: getSupportedLanguagesKeys () }}

현재 로캘 가져오기

현재 로케일의 키를 반환합니다.

{{ LaravelLocalization:: getCurrentLocale () }}

현재 로캘 이름 가져오기

현재 로케일의 이름을 문자열(영어/스페인어/아랍어/ ..etc)로 반환합니다.

{{ LaravelLocalization:: getCurrentLocaleName () }}

현재 로케일 기본 이름 가져오기

현재 로케일의 기본 이름을 문자열(English/Español/عربى/ ..etc)로 반환합니다.

{{ LaravelLocalization:: getCurrentLocaleNative () }}

현재 로캘 지역 이름 가져오기

현재 로캘의 지역 이름을 문자열(en_GB/en_US/fr_FR/ ..etc)로 반환합니다.

{{ LaravelLocalization:: getCurrentLocaleRegional () }}

현재 로캘 방향 가져오기

현재 로캘의 방향을 문자열(ltr/rtl)로 반환합니다.

{{ LaravelLocalization:: getCurrentLocaleDirection () }}

현재 로캘 스크립트 가져오기

현재 로케일 스크립트에 대한 ISO 15924 코드를 문자열로 반환합니다. "Latn", "Cyrl", "Arab" 등

{{ LaravelLocalization:: getCurrentLocaleScript () }}

view-base-path를 현재 로케일로 설정

현재 로케일을 view-base-path로 설정하려면 미들웨어 LaravelLocalizationViewPath 등록하세요.

이제 번역 파일과 같은 언어 기반 폴더에 뷰를 래핑할 수 있습니다.

resources/views/en/ , resources/views/fr , ...

나만의 맞춤 언어 URL 세그먼트 매핑

키 이름을 변경하여 SupportLocales를 수정할 수 있으므로 en-GB 대신 uk 문자열을 사용하여 사용자 정의 언어 URL 세그먼트를 제공할 수 있습니다. 물론, 이미 존재하는 키와의 충돌을 방지해야 하며 가능한 한 오랫동안 규칙을 준수해야 합니다. 그러나 이러한 사용자 정의 키를 사용하는 경우 localesMapping 배열에 매핑을 저장해야 합니다. 이 localesMapping 은 LanguageNegotiator가 HTTP Accept Language Header를 기반으로 원하는 로케일을 올바르게 할당할 수 있도록 하는 데 필요합니다. 다음은 HTTP Accept Language Header 'en-GB'를 URL 세그먼트 'uk'에 매핑하는 방법에 대한 간단한 예입니다.

 // config/laravellocalization.php

' localesMapping ' => [
	' en-GB ' => ' uk '
],

그 후 http://url-to-laravel/en-GB/a/b/c http://url-to-laravel/uk/a/b/c 가 됩니다.

LaravelLocalization:: getLocalizedURL ( ' en-GB ' , ' a/b/c ' ); // http://url-to-laravel/uk/a/b/c
LaravelLocalization:: getLocalizedURL ( ' uk ' , ' a/b/c ' ); // http://url-to-laravel/uk/a/b/c 

언어 선택기 만들기

프로젝트에서 여러 로캘을 지원하는 경우 사용자에게 언어를 변경할 수 있는 방법을 제공하고 싶을 것입니다. 다음은 고유한 언어 선택기를 만드는 데 사용할 수 있는 블레이드 템플릿 코드의 간단한 예입니다.

< ul >
    @foreach ( LaravelLocalization :: getSupportedLocales () as $localeCode => $properties )
        < li >
            < a rel = " alternate " hreflang = " {{ $localeCode } } " href = " {{ LaravelLocalization :: getLocalizedURL ( $localeCode , null , [], true ) } } " >
                {{ $properties [ ' native ' ] } }
            </ a >
        </ li >
    @endforeach
</ ul >

여기서 기본 언어는 hideDefaultLocaleInURL = true 인 경우에도 getLocalizedURL()의 URL에 강제로 표시됩니다.

경로 모델 바인딩이 지원됩니다.

번역된 경로

경로를 번역할 수 있습니다. 예를 들어 http://url/en/about 및 http://url/es/acerca(acerca는 스페인어로 되어 있음) 또는 http://url/en/article/important-article 및 http://url/ es/articulo/important-article(기사는 스페인어로 articulo임)은 다음과 같이 동일한 컨트롤러/뷰로 리디렉션됩니다.

Route::group 미들웨어에 최소한 localize 미들웨어가 로드되어 있어야 합니다(설치 지침 참조).

각 언어에 대해 routes.php resources/lang/**/routes.php 폴더에 추가하세요. 파일에는 변환 가능한 모든 경로가 포함된 배열이 포함되어 있습니다. 예를 들어 다음과 같습니다.

명심하세요: Laravel 9부터 resources/lang 폴더는 이제 루트 프로젝트 폴더( lang )에 있습니다. 프로젝트 루트에 lang 폴더가 있는 경우, lang/**/routes.php 폴더에 routes.php 를 추가해야 합니다.

 <?php
// resources/lang/en/routes.php
return [
    " about "    =>  " about " ,
    " article "  =>  " article/{article} " ,
];

 <?php
// resources/lang/es/routes.php
return [
    " about "    =>  " acerca " ,
    " article "  =>  " articulo/{article} " ,
];

다음과 같이 routes/web.php 에 경로를 추가할 수 있습니다:

Route:: group ([ ' prefix ' => LaravelLocalization:: setLocale (),
              ' middleware ' => [ ' localize ' ]], function () {

    Route:: get (LaravelLocalization:: transRoute ( ' routes.about ' ), function () {
        return view ( ' about ' );
    });

    Route:: get (LaravelLocalization:: transRoute ( ' routes.article ' ), function (  App  Article $ article ) {
        return $ article ;
    });

    //,...
});

파일이 저장되면 http://url/en/about , http://url/es/acerca , http://url/en/article/important-article 및 http://url/es/에 액세스할 수 있습니다. 기사/중요 기사는 문제 없이 처리됩니다.

변환 가능한 경로 매개변수

아마도 이전 예에서 스페인어 URL에 영어 슬러그가 있음을 발견했을 것입니다.

 http://url/es/articulo/important-article

예를 들어 다음과 같이 슬러그를 번역하는 것이 가능합니다.

 http://url/en/article/important-change
http://url/es/articulo/cambio-importante

그러나 이를 수행하려면 각 기사에 많은 슬러그(각 로케일당 하나씩)가 있어야 합니다. 이 관계를 구현하는 방법은 귀하에게 달려 있습니다. 변환 가능한 경로 매개변수에 대한 유일한 요구사항은 관련 모델이 LocalizedUrlRoutable 인터페이스를 구현한다는 것입니다.

LocalizedUrlRoutable 구현

McamaraLaravelLocalizationInterfacesLocalizedUrlRoutable 구현하려면 getLocalizedRouteKey($locale) 함수를 만들어야 합니다. 이 함수는 주어진 로케일에 대해 번역된 슬러그를 반환해야 합니다. 위의 예에서 모델 기사 내부의 getLocalizedRouteKey('en') important-change 반환해야 하고 getLocalizedRouteKey('es') cambio-importante 반환해야 합니다.

경로 모델 바인딩

경로 모델 바인딩을 사용하려면 모델의 resolveRouteBinding($slug) 함수를 덮어써야 합니다. 이 함수는 번역된 슬러그 $slug 에 속하는 모델을 반환해야 합니다. 예를 들어:

 public function resolveRouteBinding ( $ slug )
{
        return static :: findByLocalizedSlug ( $ slug )-> first () ?? abort ( 404 );
}

튜토리얼 비디오

변환 가능한 경로 매개변수를 설정하는 방법을 보여주는 이 비디오를 확인해 보세요.

이벤트

번역하려는 경우 번역 중에 URL 매개변수를 캡처할 수 있습니다. 이렇게 하려면 다음과 같이 routes.translation 이벤트에 대한 이벤트 리스너를 생성하십시오.

Event:: listen ( ' routes.translation ' , function ( $ locale , $ attributes )
{
	// Do your magic

	return $ attributes ;
});

로케일과 속성을 클로저에 매개변수로 전달해야 합니다. 이벤트 구독자를 사용할 수도 있습니다. http://laravel.com/docs/events#event-subscribers를 참조하세요.

캐싱 경로

경로를 캐시하려면 다음을 사용하세요.

php artisan route:trans:cache

... 일반적인 route:cache 명령 대신. artisan route:cache 사용하면 올바르게 작동하지 않습니다 !

경로 캐싱 솔루션이 작동하려면 애플리케이션 경로 제공을 약간 조정해야 합니다.

라라벨 11 이전

앱의 RouteServiceProvider 에서 LoadsTranslatedCachedRoutes 특성을 사용하세요.

 <?php
class RouteServiceProvider extends ServiceProvider
{
    use  Mcamara  LaravelLocalization  Traits LoadsTranslatedCachedRoutes;

라라벨 11 이후

앱의 AppServiceProvider 에서 등록 메서드의 CachedTranslatedRouteLoader 클래스를 사용합니다.

 <?php
class AppServiceProvider extends ServiceProvider
{  
    use  Mcamara  LaravelLocalization  Traits LoadsTranslatedCachedRoutes;
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        RouteServiceProvider:: loadCachedRoutesUsing ( fn () => $ this -> loadCachedRoutes ());
        . . .
    }   

자세한 내용은 여기를 참조하세요.

일반적인 문제

POST가 작동하지 않습니다

Routes::group 내부에 있는 작업 경로를 현지화하지 않으면 이런 일이 발생할 수 있습니다. 이로 인해 리디렉션이 발생하고 게시 요청이 가져오기 요청으로 변경될 수 있습니다. 이를 방지하려면 간단히 현지화 도우미를 사용하세요.

예를 들어, Auth::routes() 사용하고 이를 Route::group 에 넣으면

 <form action="/logout" method="POST">
<button>Logout</button>
</form>

작동하지 않습니다. 대신에 다음을 사용해야 합니다.

<form action ="{{  LaravelLocalization:: localizeURL ( ' /logout ' ) }} " method= " POST ">
<button>Logout</button>
</form>

이 문제를 해결하는 또 다른 방법은 이러한 유형의 요청 처리를 방지하기 위해 http 메소드를 'laravellocalization.httpMethodsIgnored'로 구성하는 것입니다.

MethodNotAllowedHttpException

게시물 URL을 현지화하지 않고 리디렉션 미들웨어를 사용하는 경우 게시물 요청이 get 요청으로 리디렉션됩니다. 그러한 가져오기 경로를 정의하지 않은 경우 이 예외가 발생합니다.

게시물 URL을 현지화하려면 POST가 작동하지 않음의 예를 참조하세요.

유효성 검사 메시지는 기본 로캘에만 있습니다.

이는 게시물 URL을 현지화하지 않은 경우에도 발생합니다. 게시물 URL을 현지화하지 않으면 유효성을 검사하는 동안 기본 로캘이 설정되고 back() 으로 돌아오면 기본 로캘에 유효성 검사 메시지가 표시됩니다.

게시물 URL을 현지화하려면 POST가 작동하지 않음의 예를 참조하세요.

테스트

테스트 설정 중에는 호출된 경로가 아직 알려지지 않았습니다. 이는 언어를 설정할 수 없음을 의미합니다. 테스트 중에 요청이 이루어지면 404가 발생합니다. 접두사를 설정하지 않으면 현지화된 경로가 존재하지 않는 것 같습니다.

이 문제를 해결하려면 이 함수를 사용하여 언어 접두사를 수동으로 설정할 수 있습니다.

 // TestCase.php
protected function refreshApplicationWithLocale ( $ locale )
{
    self :: tearDown ();
    putenv (LaravelLocalization:: ENV_ROUTE_KEY . ' = ' . $ locale );
    self :: setUp ();
}

protected function tearDown (): void
{
    putenv (LaravelLocalization:: ENV_ROUTE_KEY );
    parent :: tearDown ();
}

// YourTest.php
public function testBasicTest ()
{
    $ this -> refreshApplicationWithLocale ( ' en ' );
    // Testing code
}

협력자

• 아담 닐슨(iwasherefirst2)

그들 중 하나가 되고 싶다면 맥마라에게 물어보세요!

변경 내역

여기에서 변경 내역 보기 -> 변경 내역

특허

Laravel Localization은 MIT 라이센스에 따라 라이센스가 부여된 오픈 소스 laravel 패키지입니다.