README

简介

保持项目翻译的正确更新是繁琐的。通常翻译者没有访问代码库的权限，即使他们有，也很难跟踪每种语言的缺失翻译，或者原始文本的更新需要修订翻译。

此包允许开发人员利用数据库和缓存来管理多语言网站，同时在开发过程中仍然可以处理语言文件，并从 Laravel 翻译包的所有功能中受益，如复数或替换。

WAAVI 是一家位于西班牙马德里的网络开发工作室。您可以在 waavi.com 上了解更多关于我们的信息。

目录

• Laravel 兼容性
• 功能概述
• 安装
• 设置翻译源
  • 从文件加载翻译
  • 从数据库加载翻译
  • 混合模式
  • 将您的文件加载到数据库中
• 缓存翻译
• 在数据库中管理语言和翻译
  • 管理语言
  • 管理翻译
• 模型属性翻译
• URI 本地化
• Docker

Laravel 兼容性

功能概述

• 允许动态更改网站的文本和翻译。
• 缓存您的本地化条目。
• 将您的翻译文件加载到数据库中。
• 强制您的 URL 本地化（例如：/home -> /es/home），并通过浏览器的配置自动设置区域设置。
• 本地化您的模型属性。

安装

通过 composer 强制

composer require waavi/translation 2.5.x

或手动编辑您的 composer.json 文件

"require": {
	"waavi/translation": "2.5.x"
}

安装完成后，在您的项目 config/app.php 文件中，将以下 providers 数组条目替换为

Illuminate\Translation\TranslationServiceProvider::class

以下内容

Waavi\Translation\TranslationServiceProvider::class

删除您的配置缓存

php artisan config:clear

发布配置文件和迁移

php artisan vendor:publish --provider="Waavi\Translation\TranslationServiceProvider"

执行数据库迁移

php artisan migrate

您可以在以下位置查看包的配置文件

config/translator.php

翻译源

此包允许您从常规 Laravel 本地化文件（在 /resources/lang 中），从数据库，从缓存或从上述三者中的一种或多种加载翻译，以开发混合模式。您可以通过 translator.php 配置文件和/或 TRANSLATION_SOURCE 环境变量配置所需的操作模式。接受值包括

• 'files' 从 Laravel 的语言文件（默认）加载翻译
• 'database' 从数据库加载翻译
• 'mixed' 从文件系统和数据库加载翻译，以文件系统为主
• 'mixed_db' 从文件系统和数据库加载翻译，以数据库为主。[v2.1.5.3]

注意：将包添加到现有 Laravel 项目时，必须使用 'files' 直到执行迁移。

有关缓存配置，请参阅 缓存配置

从文件加载翻译

如果您不希望利用数据库进行翻译，您可以选择仅通过语言文件加载语言行。此模式与 Laravel 不同之处在于，如果指定的区域设置中没有找到行，则我们首先检查默认语言中的条目。如果您希望独家使用此模式，您需要设置 'available_locales' 配置文件

config/translator.php
	'available_locales' => ['en', 'es', 'fr'],

示例

默认语言为'en'时，en/validations.php中的内容是

		[
			'missing_name'			=>	'Name is missing',
			'missing_surname'		=>	'Surname is missing',
		];

es/validations.php中的内容是

		[
			'missing_name'			=>	'Falta el nombre',
		];

以'es'语言环境输出的不同键的内容

		trans('validations.missing_name'); 		// 		'Falta el nombre'
		trans('validations.missing_surname'); 	// 		'Surname is missing'
		trans('validations.missing_email'); 	// 		'validations.missing_email'

从数据库加载翻译

您可以选择仅从数据库加载翻译。如果您打算允许用户或管理员实时编辑网站文本和翻译，这将非常有用。在实际生产环境中，通常需要启用翻译的缓存来激活此源模式。有关使用此源模式的步骤详情，请参阅将文件加载到数据库中。

示例

语言表中的内容是

	| id | locale | name    |
	-------------------------
	| 1  | en     | english |
	| 2  | es     | spanish |

语言_entries表中的相关内容是

	| id | locale | namespace | group       | item	          | text                    |
	-------------------------------------------------------------------------------------
	| 1  | en     | *         | validations | missing.name    | Name is missing         |
	| 2  | en     | *         | validations | missing.surname | Surname is missing      |
	| 3  | en     | *         | validations | min_number      | Number is too small     |
	| 4  | es     | *         | validations | missing.name    | Falta nombre   			|
	| 5  | es     | *         | validations | missing.surname | Falta apellido 			|

以'es'语言环境输出的不同键的内容

		trans('validations.missing.name');   //    'Falta nombre'
		trans('validations.min_number');     //    'Number is too small'
		trans('validations.missing.email');  //    'missing_email'

混合模式

在混合模式下，在查找一组语言行时，既会查询语言文件也会查询数据库。文件系统中的条目优先于数据库中的条目。在开发阶段，此源模式很有用，因为它考虑了文件系统和用户条目。

示例

When files and database are set like in the previous examples:

		trans('validations.missing_name');     //    'Falta el nombre'
		trans('validations.missing_surname');  //    'Falta apellido'
		trans('validations.min_number');       //    'Number is too small'
		trans('validations.missing_email');    //    'missing_email'

将您的文件加载到数据库中

当使用数据库或混合翻译源时，您需要首先将翻译加载到数据库中。为此，请按照以下步骤操作

• 运行安装说明中详细说明的迁移。

• 将您选择的语言添加到数据库中（见管理数据库语言）

• 使用提供的Artisan命令将语言文件加载到数据库中

  php artisan translator:load

执行Artisan命令时，将发生以下情况

• 将创建不存在的条目。
• 现有条目将被更新（除非它们被锁定）。当允许用户实时编辑翻译时，建议您通过在翻译仓库中提供的updateAndLock方法进行。这样可以防止在从文件重新加载翻译时覆盖条目。
• 当编辑默认语言环境中的条目时，所有翻译都将被标记为待审查。这给翻译者提供了审查可能不正确的翻译的机会，但不会删除它们，以避免源文本中的细微误差更改删除所有翻译。有关如何处理不稳定翻译的详细信息，请参阅管理翻译。

支持供应商文件和子目录。请注意，当在子目录中加载条目时，Laravel 5已更改语法为

	trans('subdir/file.entry')
	trans('package::subdir/file.entry')

缓存翻译

由于每次加载语言组时查询数据库效率低下，您可以选择利用Laravel的缓存系统。此模块将使用您在app/config/cache.php中定义的相同缓存配置。

您可以通过translator.php配置文件或'TRANSLATION_CACHE_ENABLED'环境变量启用或禁用缓存。配置选项是

缓存标签

自版本2.1.3.8起可用，如果使用的缓存存储允许使用标签，则TRANSLATION_CACHE_SUFFIX将用作所有缓存条目的通用标签。建议这样做，以便能够仅使翻译缓存无效，甚至仅针对给定的语言环境、命名空间和组配置。

清除缓存

自版本2.1.3.8起可用，您可以通过Artisan命令和外观清除翻译缓存。如果使用缓存标签，则仅清除翻译缓存。如果不可用缓存标签，则将清除您的所有应用程序缓存。

缓存刷新命令

php artisan translator:flush

要访问翻译缓存，请将以下别名添加到您的config/app.php文件中

    'aliases'         => [
        /* ... */
        'TranslationCache' => \Waavi\Translation\Facades\TranslationCache::class,
    ]

完成后，您可以通过调用以下方法来清除整个翻译缓存：

    \TranslationCache::flushAll();

您还可以选择只使指定区域设置、命名空间和组组合无效。

    \TranslationCache::flush($locale, $group, $namespace);

• 区域设置是您希望清除的语言区域。
• 命名空间是 '*' 用于您的应用程序翻译文件，或 'package' 用于供应商翻译文件。
• 组变量是您希望清除的翻译文件的路径。

例如，假设我们在 resources/lang 目录中有以下文件：en/auth.php、en/auth/login.php 和 en/vendor/waavi/login.php。要清除它们的缓存条目，您将调用：

    \TranslationCache::flush('en', 'auth', '*');
    \TranslationCache::flush('en', 'auth/login', '*');
    \TranslationCache::flush('en', 'login', 'waavi');

在数据库中管理语言和翻译

管理语言和翻译的推荐方式是通过提供的存储库。您可以通过直接通过语言和翻译模型保存更改来规避此方法，但是模型保存时不再自动执行验证，可能会导致不稳定和错误。

语言和翻译存储库都提供了以下方法

管理语言

应通过 \Waavi\Translation\Repositories\LanguageRepository 进行语言管理，以确保在插入和更新之前进行适当的数据验证。建议您通过依赖注入实例化此类。

有效的语言记录需要其名称和区域设置都是唯一的。建议您使用每种语言的本地名称（例如：英语、西班牙语、法语）。

提供的方法有

管理翻译

应通过 \Waavi\Translation\Repositories\TranslationRepository 进行翻译管理，以确保在插入和更新之前进行适当的数据验证。建议您通过依赖注入实例化此类。

有效的翻译条目不能与其他条目具有相同的区域设置和语言代码。

提供的方法有

需要考虑的事项

• 您可以锁定翻译，以便只能通过 updateAndLock 来更新。语言文件加载器使用更新方法，将无法覆盖已锁定的翻译。
• 当更新属于默认区域设置的文本条目时，所有其兄弟项都会被标记为待审核。
• 当删除条目时，如果它属于默认区域设置，其翻译也将被删除。

模型属性翻译

您还可以使用翻译管理系统来管理模型属性翻译。为此，您只需

• 确保数据库或混合源已设置。
• 确保您的模型使用 Waavi\Translation\Translatable\Trait
• 在您的模型中，添加一个 translatableAttributes 数组，包含您希望可用于翻译的属性名称。
• 对于您希望翻译的每个字段，请确保数据库中存在相应的 attributeName_translation 字段。

示例

	\Schema::create('examples', function ($table) {
        $table->increments('id');
        $table->string('slug')->nullable();
        $table->string('title')->nullable();
        $table->string('title_translation')->nullable();
        $table->string('text')->nullable();
        $table->string('text_translation')->nullable();
        $table->timestamps();
    });

    class Example extends Model
	{
	    use \Waavi\Translation\Traits\Translatable;
	    protected $translatableAttributes = ['title', 'text'];
	}

URI 本地化

您可以使用 Waavi\Translation\Middleware\TranslationMiddleware 确保所有 URL 都得到适当的本地化。TranslationMiddleware 仅为没有区域设置的 GET 请求进行重定向。

例如，如果用户访问 URL /home，以下操作会发生：

• 中间件将检查是否存在区域设置。
• 如果存在有效的区域设置
  • 它将为该区域设置全局设置语言
  • 以下数据将在您的视图中可用
    • currentLanguage: 当前选择的 Language 实例。
    • selectableLanguages: 访问者可以切换到的所有语言列表（除了当前语言）
    • altLocalizedUrls: 当前资源除当前之外的所有本地化 URL 列表，格式为 ['locale' => 'en', 'name' => 'English', 'url' => '/en/home']
• 如果没有区域设置
  • 检查浏览器接受的区域设置 HTTP_ACCEPT_LANGUAGE 的前两个字母（例如 'en-us' => 'en'）
  • 如果是有效的区域设置，则将访问者重定向到该区域设置 => /es/home
  • 如果不是，则重定向到默认区域设置 => /en/home
  • 重定向将保留 URL 中的输入数据（如果有）

您可以选择通过将中间件添加到您的 App\Http\Kernel 文件中全局启用此中间件

	protected $middleware = [
		/* ... */
        \Waavi\Translation\Middleware\TranslationMiddleware::class,
    ]

或者通过应用 ‘localize’ 路由中间件来有选择性地应用，该中间件在通过 ServiceProvider 安装包时已注册。

建议您将以下别名添加到您的 config/app.php 别名中

	'aliases'         => [
		/* ... */
		'UriLocalizer'	=> Waavi\Translation\Facades\UriLocalizer::class,
    ];

每个本地化路由都必须以当前语言环境作为前缀

	// If the middleware is globally applied:
	Route::group(['prefix' => \UriLocalizer::localeFromRequest()], function(){
		/* Your routes here */
	});

	// For selectively chosen routes:
	Route::group(['prefix' => \UriLocalizer::localeFromRequest(), 'middleware' => 'localize')], function () {
	    /* Your routes here */
	});

从 v2.1.6 版本开始，您还可以指定 URL 中语言段的自定义位置。例如，如果语言信息是 URL 的第三个部分（/api/v1/es/my_resource），则可以使用

    // For selectively chosen routes:
    Route::group(['prefix' => 'api/v1'], function() {
        /** ... Non localized urls here **/

        Route::group(['prefix' => \UriLocalizer::localeFromRequest(2), 'middleware' => 'localize:2')], function () {
            /* Your localized routes here */
        });
    });

在视图中，对于中间件激活的路由，您可以使用共享变量向用户提供一个菜单，以便从当前语言切换到另一种语言。例如

<li class="dropdown">
    <a href="#" class="dropdown-toggle" data-toggle="dropdown">{{ $currentLanguage->name }} <b class="caret"></b></a>
    <ul class="dropdown-menu">
        @foreach ($altLocalizedUrls as $alt)
            <li><a href="{{ $alt['url'] }}" hreflang="{{ $alt['locale'] }}">{{ $alt['name'] }}</a></li>
        @endforeach
    </ul>
</li>

Docker

拉取 Docker 镜像：docker-compose pull

安装包：docker-compose run translation composer install

更新包：docker-compose run translation composer update

运行测试：docker-compose run translation composer test