eklundkristoffer/js-localization

Laravel包,用于为JavaScript代码提供本地化。

1.1 2018-11-12 05:17 UTC

This package is auto-updated.

Last update: 2024-09-12 19:19:39 UTC


README

Build Status Scrutinizer Code Quality Code Coverage Total Downloads

这是一个简单、易用且灵活的Laravel Web框架的包。允许您在JavaScript代码中使用Laravel Webapp的本地化消息(请参阅resources/lang目录)。您可以轻松配置需要导出的消息。

⚠️正在寻找新的维护者。如果您感兴趣,请与我联系。

分支

安装

将以下行添加到Laravel Webapp的composer.json文件的require部分

    "require": {
        "andywer/js-localization": "dev-laravel-5"    // "dev-laravel-4.1", "dev-laravel-4.2" for Laravel 4
    }

运行composer update以安装包。

最后将以下行添加到app/config/app.php文件的providers数组中

    'providers' => [
        /* ... */
        JsLocalization\JsLocalizationServiceProvider::class
    ]

配置

首先运行php artisan vendor:publish。此命令将包的默认配置复制到config/js-localization.php

现在您可以编辑此文件,以定义在JavaScript代码中需要的消息。只需编辑配置文件中的messages数组。

示例(导出所有提醒消息)

<?php

return [
    // Set the locales you use
    'locales' => ['en'],

    // Set the keys of the messages you want to use in javascript
    'messages' => [
        'passwords' => [
            'password', 'user', 'token'
        ]
    ],

    /*
     * in short:
     * 'messages' => ['passwords']
     *
     *
     * you could also use:
     *
     * 'messages' => [
     *     'passwords.password',
     *     'passwords.user',
     *     'passwords.token'
     * ]
     */
     
    // Set the keys of config properties you want to use in javascript.
    // Caution: Do not expose any configuration values that should be kept privately!
    'config' => [
        'app.debug'
    ],
     
    // Disables the config cache if set to true, so you don't have to run `php artisan js-localization:refresh`
    // each time you change configuration files.
    // Attention: Should not be used in production mode due to decreased performance.
    'disable_config_cache' => false,

    // Split up the exported messages.js file into separate files for each locale.
    // This is to ensue faster loading times so one doesn't have to load translations for _all_ languages.
    'split_export_files' => true,
];

重要

当第一次使用JsLocalizationController时,消息配置将被缓存。更改消息配置后,您需要调用php artisan js-localization:refresh来刷新缓存。这也影响了导出到JavaScript的配置属性,因为它们也被缓存了。

用法

JavaScript的翻译资源可以通过您的Laravel应用程序在运行时提供,也可以作为静态JavaScript文件预先生成,这使得您可以直接从您的Web服务器或CDN提供它们,或将它们包含在您的构建过程中。

运行时生成

您只需将必要的<script>标签添加到您的布局中。以下是一个示例blade视图

@include('js-localization::head')
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Test view</title>
        @yield('js-localization.head')
    </head>
    <body>
        <p>
            Here comes a translated message:
            <script type="text/javascript">
                document.write( Lang.get('reminder.user') );
            </script>
        </p>
    </body>
</html>

请记住,最好不要将@yield('js-localization.head')放在<head>中,因为它包含发送前端部分的<script>标签。最佳实践是在<body>的末尾放置它,但在其他<script>标签之前。上面的示例只是将其包含在头部,因为这是最简单的使用形式。

静态生成

为了提高性能,可以生成包含所有生成字符串的静态JavaScript文件。这些文件可以直接作为静态文件提供,或作为前端资产构建过程的一部分包含在内。

要指定资产输出目录,只需在config/js-localization.php文件中将$storage_path字符串相应设置(请参阅配置)。

    /*
    |--------------------------------------------------------------------------
    | Define the target to save the exported messages to
    |--------------------------------------------------------------------------
    |
    | Directory for storing the static files generated when using file storage.
    |
    */

    'storage_path' => public_path('vendor/js-localization/'),

然后可以使用artisan命令生成文件

php artisan js-localization:export

这将在其目标目录中生成两个文件

  • messages.js包含您的翻译字符串
  • config.js包含您导出的配置值

如果您想自动将messages.js文件分割成针对每个语言环境的单独.js文件,您可以在config/js-localization.php配置文件中将以下设置为true

    'split_export_files' => true,

这将在目标目录中生成以下文件

  • lang-{locale}.js包含一种语言的翻译字符串,如果将split_export_files配置选项设置为true

请记住,每次编辑、添加或删除任何翻译字符串时,都需要使用php artisan js-localization:export重新生成这些文件。

功能

您可以在您的JavaScript代码中使用Lang.get()、Lang.has()、Lang.choice()、Lang.locale()和trans()(Lang.get()的别名)以及Config.get()。它们与Laravel的Lang外观一样工作。此外,您还可以将配置属性传递到您的JavaScript代码中。在JavaScript中也有Config.get()。使用config/js-localization.php中的config字段配置要传递给客户端的配置属性。注意:不要导出任何安全关键属性,如数据库凭证等,因为它们将对所有使用您应用程序的人可见!

消息中的变量是支持的。例如:"This is my test string for :name."

复数形式也受支持,但不会考虑地区。它仅使用英语复数规则("singular text|plural text")。更复杂的复数量词尚未支持。

服务提供商

假设您正在开发一个依赖此JavaScript本地化功能的laravel包,并且您想要配置您包中哪些消息需要对JS代码可见。

幸运的是,这很简单。只需监听JsLocalization.registerMessages事件,并使用JsLocalization\Facades\JsLocalizationHelper::addMessagesToExport()方法。如下所示

<?php

use Illuminate\Support\ServiceProvider;
use JsLocalization\Facades\JsLocalizationHelper;

class MyServiceProvider extends ServiceProvider
{
    /* ... */

    public function register()
    {
        Event::listen('JsLocalization.registerMessages', function()
        {
            JsLocalizationHelper::addMessagesToExport([
                // list the keys of the messages here, similar
                // to the 'messages' array in the config file
            ]);
        });
    }

    /* ... */
}

许可协议

本软件在MIT许可下发布。请参阅许可协议