README

Laravel Gettext 是一个与优秀的 Laravel PHP 框架兼容的包。它提供了一个简单的方法来为 Laravel 应用程序添加本地化支持。它旨在与 GNU gettext 和 Poedit 一起工作。此包的早期版本（4.x 之前）与本机 php-gettext 模块一起工作。当前版本默认使用 Symfony 翻译包而不是本机 php 扩展。

最新 Laravel 5.3.x 稳定版本（4.0.4）

注意：此文档适用于 laravel 5.3.x 和 4.x 分支。对于旧版本的 Laravel，请参阅以下链接

旧版本

最新 Laravel 5.2.x 稳定版本（3.1.0）

最新 Laravel 5.1.x 稳定版本（3.0.3）

最新 Laravel 5.0 稳定版本（2.0.3）

最新 Laravel 4.x 稳定版本（1.0.3）

开发 master 不稳定，仅用于开发（dev-master）

1. 要求

如果需要使用本机 php-gettext 扩展，则以下为可选要求

php-gettext - https://php.ac.cn/manual/en/book.gettext.php
系统（和生成服务器！）上的 GNU gettext - https://gnu.ac.cn/software/gettext/

为了使用本机 php-gettext 模块，您需要将 'handler' 选项更新为 'gettext'。

2. 安装

将composer仓库添加到您的composer.json文件中

    "xinax/laravel-gettext": "4.x"

然后运行composer update。一旦安装完成，您可以在config/app.php的providers数组中注册服务提供者

    'providers' = [
        // ...
        Xinax\LaravelGettext\LaravelGettextServiceProvider::class,
        // ...
    ]

现在您需要发布配置文件以设置自己的应用程序值

    php artisan vendor:publish

此命令将在：config/laravel-gettext.php中创建包配置文件。

您还需要在app/Http/Kernel.php文件中注册LaravelGettext中间件

    protected $middlewareGroups = [
        'web' => [
            // ...
            \Xinax\LaravelGettext\Middleware\GettextMiddleware::class,
        ],
        // ...
    ]

请确保在Illuminate\Session\Middleware\StartSession之后添加该行，否则区域设置不会被保存到会话中。

3. 配置

此时，您的应用程序已完全支持gettext。现在您需要在config/laravel-gettext.php中设置一些配置值。

    /**
     * Default locale: this will be the default for your application all
     * localized strings. Is to be supposed that all strings are written
     * on this language.
     */
    'locale' => 'es_ES',

    /**
     * Supported locales: An array containing all allowed languages
     */
    'supported-locales' => array(
        'es_ES',
        'en_US',
        'it_IT',
        'es_AR',
    ),

    /**
     * Default charset encoding.
     */
    'encoding' => 'UTF-8',

好的，现在已配置完成。是时候首次生成目录结构和翻译文件了。

在运行此命令之前，请确保您有对resources/的写入权限

    php artisan gettext:create

此命令将在resources/lang/i18n上创建所需的目录和文件

4. 工作流程

A. 编写字符串 :D

默认情况下，LaravelGettext会在app/Http/Controllers和resources/views中进行递归搜索以查找翻译。所有翻译都是以__()函数打印的文本。让我们看看一个简单的视图示例

    // an example view file
    echo 'Non translated string';
    echo __('Translated string');
    echo __('Another translated string');
    // with parameter
    $str = 'parameter';
    $n = 2;
    echo __('Translated string with %s', $str);
    echo __('%dnd translated string with %s', [$n, $str]);

    // an example view in blade
    {{ __('Translated string') }}

Poedit不支持blade语法。当使用blade视图时，必须在更新翻译到Poedit之前运行php artisan gettext:update以编译所有blade视图为纯PHP

B. 复数字符串

复数翻译遵循上述相同模式。复数翻译是以_n()函数打印的文本，并遵循php ngettext。让我们看看一个简单的视图示例

    // an example view file
    $n = 2;
    echo ($n > 1) ? 'Non translated plural string' : 'Non translated string';
    echo _n('Translated string', 'Translated plural string', $n);
    // with parameter
    $str = 'parameter';
    echo _n('Translated string %s', 'Translated plural string %s', 2, $str);

    // an example view in blade
    {{ _n('Translated string', 'Translated plural string', $n) }}

Poedit的关键词在配置文件中以默认模式定义

    ['_n:1,2', 'ngettext:1,2']

请参阅Poedit使用的复数形式以配置您的语言。

C. 使用Poedit进行翻译

使用Poedit打开您想要翻译的语言的PO文件。PO文件默认位于resources/lang/i18n/[locale]/LC_MESSAGES/[domain].po。如果您有多个gettext域，则每个域都会生成一个文件。

加载Poedit后，按更新按钮加载所有本地化字符串。每次添加新的本地化字符串时，您都可以重复此步骤。

在Poedit中填写翻译字段并保存文件。第一次这样做时，将为每个区域生成MO文件。

C. 运行时方法

要更改运行时配置，您有以下方法

    /**
     * Sets the Current locale.
     * Example param value: 'es_ES'
     *
     * @param mixed $locale the locale
     * @return LaravelGettext
     */
    LaravelGettext::setLocale($locale);

    /**
     * Gets the Current locale.
     * Example returned value: 'es_ES'
     *
     * @return String
     */
     LaravelGettext::getLocale();

    /**
     * Gets the language portion of the locale.
     * Eg from en_GB, returns en
     *
     * @return mixed
     */
    LaravelGettext::getLocaleLanguage()

    /**
     * Sets the Current encoding.
     * Example param value: 'UTF-8'
     *
     * @param mixed $encoding the encoding
     * @return LaravelGettext
     */
     LaravelGettext::setEncoding($encoding);

    /**
     * Gets the Current encoding.
     * Example returned value: 'UTF-8'
     *
     * @return String
     */
     LaravelGettext::getEncoding();

    /**
     * Sets the current domain
     *
     * @param String $domain
     */
    LaravelGettext::setDomain($domain);

    /**
     * Returns the current domain
     *
     * @return String
     */
    LaravelGettext::getDomain();

    /**
     * Returns the language selector object
     *
     * @param  Array $labels
     * @return LanguageSelector
     */
    LaravelGettext::getSelector($labels = []);

5. 特性和示例

A. 路由和控制器实现示例

app/Http/routes.php

    Route::get('/lang/{locale?}', [
        'as'=>'lang',
        'uses'=>'HomeController@changeLang'
    ]);

app/Http/Controllers/HomeController.php

    /**
     * Changes the current language and returns to previous page
     * @return Redirect
     */
    public function changeLang($locale=null)
    {
        LaravelGettext::setLocale($locale);
        return Redirect::to(URL::previous());
    }

B. 基本语言选择器示例

  <ul>
      @foreach(Config::get('laravel-gettext.supported-locales') as $locale)
            <li><a href="/lang/{{$locale}}">{{$locale}}</a></li>
      @endforeach
  </ul>

C. 内置语言选择器

您可以在视图中使用内置的语言选择器

    // Plain php:
    LaravelGettext::getSelector()->render();

    // Blade views:
    {!! LaravelGettext::getSelector()->render() !!}

它还支持自定义标签

    LaravelGettext::getSelector([
        'en_US' => 'English',
        'es_ES' => 'Spanish',
        'de_DE' => 'Deutsch',
    ])->render();

D. 添加源目录和域

您可以通过编辑source-paths配置数组来实现这一点。默认情况下，resources/views和app/Http/Controllers已设置。

    /**
     * Paths where Poedit will search recursively for strings to translate.
     * All paths are relative to app/ (don't use trailing slash).
     *
     * Remember to call artisan gettext:update after change this.
     */
    'source-paths' => array(
        'Http/Controllers',
        '../resources/views',
        'foo/bar',              // app/foo/bar
    ),

您可能希望将翻译放在不同的文件中。在GNUGettext中，翻译通过域分开，域仅仅是上下文名称。

Laravel-Gettext始终设置一个默认域，它包含所有不属于任何域的路径，其名称由'domain'配置选项确定。

要添加新域，只需将路径包裹在所需的域名中，如下例所示

    'source-paths' => array(
        'frontend' => array(
            'Http/Controllers',
            '../resources/views/frontend',
        ),
        'backend' => array(
            '../resources/views/backend',
        ),
        '../resources/views/misc',
    ),

此配置将为每种语言生成三个翻译文件：messages.po、frontend.po和backend.po

要更改当前域的运行时（路由中间件是一个很好的位置来执行此操作）

    LaravelGettext::setDomain("backend");

记住：每次更改'source-paths'选项时，请务必更新gettext文件，否则是不必要的。

    php artisan gettext:update

此命令将更新您的 PO 文件，并保持现有翻译不变。之后，您可以打开 Poedit 并点击更新按钮，以将新路径中的新文本字符串添加进去。

您只能使用此命令更新同一域的文件。

    php artisan gettext:update --domain backend

E. 关于 gettext 缓存（仅适用于 php-gettext 原生模块）

有时当您在 PO 文件上编辑/添加翻译时，更改不会立即出现。这是因为 gettext 缓存系统保留了内容。最快速的解决办法是重启您的 web 服务器。

6. 贡献

如果您想帮助开发此包，您可以

在问题部分报告您发现的错误
发送带有您补丁的 pull request 给我
修复文档/注释中的灾难性英文；-)
创建分支并创建您自己的 laravel-gettext 版本
给一个 star！

now-here / laravel-gettext

维护者

详细信息