README

将此包添加到本地化您的 Laravel 应用程序。

使用官方 Laravel 语法（使用 PHP 或 JSON 文件），或使用 GetText 语法。

仅编写源文本，并将其与 Translation.io 上的翻译者同步。

技术演示（2.5分钟）

需要帮助？ contact@translation.io

目录

• 本地化语法
  • Laravel 本地化（PHP 键/值）
  • Laravel 本地化（JSON 源文本）
  • GetText
• 安装
• 使用
  • 同步
  • 同步并显示可清除的
  • 同步并清除
• 管理语言
  • 添加或删除语言
  • 编辑语言
  • 自定义语言
• 更改当前区域设置
  • 全局
  • 本地
• 前端本地化
  • 使用此包
  • 使用我们的官方 React & JavaScript 包
• 高级配置选项
  • 忽略的 PHP 键
• 测试
• 贡献
• Translation.io 客户端列表
  • Ruby on Rails (Ruby)
  • Laravel (PHP)
  • React, React Native 和 JavaScript
  • Angular
  • 其他
• 许可证

本地化语法

Laravel 本地化（PHP 键/值）

默认 Laravel 本地化方法。

// Regular
__('inbox.title');

// Regular with sublevel key
__('inbox.menu.title');

// Pluralization
trans_choice('inbox.messages', $number);

// Interpolation
__('inbox.hello', ['name' => $user->name]);

使用 PHP 文件 lang/en/inbox.php

<?php
return [
    'title' => 'Title to be translated',
    'hello' => 'Hello :name',
    'messages' => 'One message|Many messages',
    'menu' => [
        'title' => 'Title of menu'
    ]
];

注意

• trans 也可以代替 __ 使用。
• 您可以使用子文件夹（如 en/subfolder/inbox.php）来组织 PHP 文件，使用键（如 subfolder/inbox.title）。

Laravel 本地化（JSON 源文本）

Laravel 5.4 的新功能 是可以使用 __ 与源文本（而不仅仅是与上一节中的键）一起使用。

这些翻译存储在位于 lang 目录中的 JSON 文件中。

// Regular
__("Text to be translated");

// Pluralization
trans_choice(__('One message|Many messages'), $number);

// Interpolation
__('Hello :name', ['name' => $user->name]);

使用 JSON 文件 lang/en.json

{
    "Text to be translated": "",
    "One message|Many messages": "",
    "Hello :name": ""
}

注意

• 为了减少处理多个 JSON 文件的时间，我们建议仅编辑原始语言（通常是 en.json）以添加新字符串，并将翻译留空。在 同步 过程中，此包将自动创建并填充目标语言的 JSON 文件。

• 如果您想按功能组织 JSON 文件，您可以在 AppServiceProvider 中注册新路径，如下所示

public function boot()
{
    $loader = $this->app['translation.loader'];

    // or 'resources/lang/my_feature' in Laravel < 9
    $loader->addJsonPath(base_path('lang/my_feature')); 
}

GetText

此包将 GetText 支持添加到 Laravel。我们 强烈建议 您使用 GetText 来本地化应用程序，因为它允许更简单、更完整的语法。

此外，您不需要创建和管理任何 PHP 或 JSON 文件，因为您的代码将被自动扫描以查找任何需要翻译的字符串。

// Regular
t("Text to be translated");

// Pluralization
n("Singular text", "Plural text", $number);

// Regular with context
p("context", "Text to be translated");

// Pluralization with context
np("context", "Singular text", "Plural text", $number);

// Simple Interpolations (works with n, p and np too)
t('Hello %s', $user->name);

// Complex Interpolations (works with n, p and np too)
t(':city1 is bigger than :city2', [ ':city1' => 'NYC', ':city2' => 'BXL' ]);

安装

1. 通过 Composer 添加包

composer require tio/laravel

1. 从UI创建一个新的翻译项目 点击这里。
2. 将初始化器复制到您的Laravel应用中（config/translation.php）或执行php artisan vendor:publish。

初始化器看起来是这样的

<?php
return [
    'key' => env('TRANSLATIONIO_KEY'),
    'source_locale' => 'en',
    'target_locales' => ['fr', 'nl', 'de', 'es']
];

1. 在您的.env文件中添加API密钥（TRANSLATIONIO_KEY）。
2. 使用以下命令初始化您的项目并将现有翻译推送到Translation.io

php artisan translation:init

注意：由于从Laravel 9开始，lang目录和Laravel使用的默认语言文件默认情况下不包含在新项目中（请参阅官方文档），因此您可能需要运行lang:publish命令来生成它们

php artisan lang:publish

如果您将来需要添加或删除语言，请阅读本节。

使用

同步

要发送新的可翻译键/字符串并从Translation.io获取新的翻译，只需运行

php artisan translation:sync

同步并显示可清除的

如果您需要找出Translation.io中的未使用键/字符串，以当前分支作为参考

php artisan translation:sync_and_show_purgeable

正如其名所示，此操作还会同时执行同步。

同步并清除

如果您需要使用当前分支作为参考从Translation.io中删除未使用的键/字符串

php artisan translation:sync_and_purge

正如其名所示，此操作还会同时执行同步。

警告：所有不在当前本地分支中存在的键都将从Translation.io中永久删除。

管理语言

添加或删除语言

您可以通过更新'target_locales' => []在您的config/translation.php文件中添加或删除语言，并执行php artisan translation:sync。

如果您想添加带有现有翻译的新语言（例如，如果您的lang目录中已经有一个翻译的PHP文件），您需要在Translation.io上创建一个新项目，并运行php artisan translation:init才能使其出现。

编辑语言

要编辑现有语言同时保留其翻译（例如，从en更改为en-US）。

1. 在Translation.io上创建一个新的项目并指定正确的语言。
2. 调整config/translation.php（新的API密钥和语言）
3. 调整lang或resources/lang中的目录语言名称（可选：调整GetText .po标题）
4. 执行php artisan translation:init并检查一切是否正常。
5. 邀请新项目中的合作者。
6. 删除旧项目。

不幸的是，由于您创建了新项目，翻译历史和标签将丢失。

自定义语言

自定义语言始终从现有语言派生。如果您想将某些翻译适应到应用程序的另一个实例或特定客户，这很有用。

自定义语言的格式为：现有语言代码 + - + 自定义文本，其中自定义文本只能包含字母数字字符和-。

示例：en-microsoft或fr-BE-custom。

自定义语言可以像任何其他语言一样添加和使用。

更改当前区域设置

全局

使用set.locale中间件是最容易更改当前区域设置的方法。

// in routes/web.php

// Solution 1: Apply the locale selection to root.
//             => https://yourdomain.com?locale=fr
Route::get('/', function () {
    return view('welcome');
})->middleware('set.locale');

// Solution 2: Apply the locale selection to many routes.
//             => https://yourdomain.com/...?locale=fr
Route::middleware('set.locale')->group(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});

// Solution 3: prefix your routes with the locale and apply it.
//             => https://yourdomain.com/fr
//             => https://yourdomain.com/fr/...
Route::prefix('{locale?}')->middleware('set.locale')->group(function() {
    Route::get('/', function () {
        return view('welcome');
    });
});

用户第一次连接时，它将自动设置从浏览器HTTP_ACCEPT_LANGUAGE值提取的区域设置，并在请求之间将其保留在会话中。

set.locale中间件代码在这里，您可以自由地根据您自己的区域管理进行调整。

本地

使用以下方法更改当前区域设置

use Tio\Laravel\Facade as Translation;

Translation::setLocale('fr');

前端本地化

使用此包

此包还能够覆盖前端本地化（React，Vue等）。

有几种方法可以将翻译字符串从后端传递到前端：JavaScript序列化、data- HTML属性、JSON文件等。

处理React/Vue时，最简单的策略是在组件挂载时将相应的翻译作为props传递。

注意

• 您可以使用多层深度的i18n props，并将子树作为props传递给每个子组件。
• 这也非常适合服务器端渲染组件。

使用我们的官方 React & JavaScript 包

由于Translation.io直接集成在优秀的Lingui国际化框架中，您也可以将前端本地化视为一个完全不同的本地化项目。

更多详情请参阅

• 网站：https://translation.io/lingui
• GitHub页面：https://github.com/translation/lingui

高级配置选项

配置文件config/translation.php可以接受多个可选配置选项。

以下是一些选项的描述，但为了获得完整列表，请参阅translation.php。

忽略的 PHP 键

如果您想忽略特定的PHP键、整个PHP文件或子目录，可以使用ignored_key_prefixes选项。

例如

<?php
return [
    ...
    'ignored_key_prefixes' => [
        'validation',        // ignore the whole validation.php file.
        'validation.custom', // ignore the "custom" subtree in validation.php file.
        'subfolder/more',    // ignore the whole subfolder/more.php file.
    ],
    ...
];

测试

运行与最旧依赖项的规范

composer update --no-interaction --prefer-stable --prefer-lowest
./vendor/bin/phpunit

运行与最新依赖项的规范

composer update --no-interaction --prefer-stable
./vendor/bin/phpunit

贡献

请参阅CONTRIBUTING文件。

Translation.io 客户端列表

以下客户端由Translation.io官方支持，并且有很好的文档记录。

其中一些实现（以及其他非官方支持的实现）是由贡献者为他们的翻译项目开始的。我们感谢所有贡献者的辛勤工作！

Ruby on Rails (Ruby)

在https://translation.io/rails上官方支持

• GitHub：https://github.com/translation/rails
• RubyGems：https://rubygems.org.cn/gems/translation/

致谢：@aurels，@michaelhoste

Laravel (PHP)

在https://translation.io/laravel上官方支持

• GitHub：https://github.com/translation/laravel
• Packagist：https://packagist.org.cn/packages/tio/laravel

致谢：@armandsar，@michaelhoste

React, React Native 和 JavaScript

在https://translation.io/lingui上官方支持

Translation.io直接集成在优秀的Lingui国际化项目中。

• GitHub：https://github.com/translation/lingui
• NPM：https://npmjs.net.cn/package/@translation/lingui

Angular

在https://translation.io/angular上官方支持

• GitHub：https://github.com/translation/angular
• NPM：https://npmjs.net.cn/package/@translation/angular

致谢：@SimonCorellia，@didier-84，@michaelhoste

其他

如果您想为您喜爱的语言或框架创建新的客户端，请阅读我们的创建Translation.io库指南，并使用特殊的初始化和同步端点。

您还可以使用更传统的API。

如果您需要帮助或想要分享您的库，请随时通过contact@translation.io联系我们。

许可证

MIT许可（MIT）。有关更多信息，请参阅许可文件。