batons0/laravel-gettext

使用 Poedit 和 GNU gettext 以简单的方式为 Laravel 应用程序添加本地化支持。

维护者

详细信息

github.com/Batons0/laravel-gettext

主页

源代码

问题

安装量: 1,517

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 110

10.0.0 2022-11-15 21:10 UTC

Requires

Requires (Dev)

Replaces

MIT d4dcbd4b732465bc0448fd2930e5eac168b66dac

  • Nicolás Daniel Palumbo <n.woop@xinax.net>
  • Antoine Aflalo <dev+laravel_gettext.woop@zerospam.ca>

translationgettextlaravellocalizationpoEditlaravel-gettext

This package is auto-updated.

Last update: 2024-09-16 21:37:17 UTC

README

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

稳定的构建状态 laravel-gettext for Laravel 8

稳定的构建状态 laravel-gettext for Laravel 6

Laravel 最新长期支持版本是 Laravel 6，我们不推荐使用版本小于 6 的 Laravel。

1. 要求

1.1 可选

1.1.1 APCU

已安装 APCU 扩展 - https://php.ac.cn/manual/en/book.apcu.php

如果已安装 APCU php 扩展，库将使用内存来缓存已加载的翻译，以避免在每次请求时解析翻译文件（mo/po）。

当翻译文件发生变化时，缓存将自动失效。

1.1.2 gettext

如果您想使用原生 php-gettext 扩展，则是可选的要求

您需要将 'handler' 选项更新为 'gettext'，以便使用原生的 php-gettext 模块。

2. 安装

安装完成后，Laravel 将自动发现提供者并加载它。（仅适用于 5.5+）

    composer require zerospam/laravel-gettext

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

    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 中搜索翻译。所有以 _i() 函数打印的文本都是翻译。让我们看看一个简单的视图示例

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

Poedit 无法“理解”blade语法。在使用blade视图时，您必须先运行 php artisan gettext:update，将所有blade视图编译成纯PHP，然后再在Poedit中更新翻译。

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为您的语言配置使用的复数形式。

使用Symfony

如果您使用Symfony作为您的翻译后端，您可以通过_s方法访问它们的复数语法。在Poedit中，它将被视为单行而不是复数。

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

使用symfony复杂语法

    echo _s('{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples', $n);
    // with parameter
    $str = 'red';
    echo _s('{0} There are no %s apples|{1} There is one %s apple|]1,Inf[ There are %count% %s apples', 2, $str);
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
  • 修复文档/注释中的灾难性英语；-)
  • 创建一个fork并创建自己的laravel-gettext版本
  • 给一颗星！

7. 从4.*升级

如果您是从4.*升级的，即Laravel 5.3的版本，您需要重构对__方法的用法。

现在Laravel使用这种方法进行自己的翻译。您现在需要使用_i代替，并在Laravel-Gettext的配置文件中添加此关键字

此外，如果您使用Symfony作为后端，您可以添加_s方法。它旨在使用Symfony复数语法的完整功能集。

  /**
     * The keywords list used by poedit to search the strings to be translated
     *
     * The "_", "__" and "gettext" are singular translation functions
     * The "_n" and "ngettext" are plural translation functions
     * The "dgettext" function allows a translation domain to be explicitly specified
     *
     * "__" and "_n" and "_i" and "_s" are helpers functions @see \Xinax\LaravelGettext\Support\helpers.php
     */
    'keywords-list' => ['_', '__', '_i', '_s', 'gettext', '_n:1,2', 'ngettext:1,2', 'dgettext:2'],;