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 Middleware最简单的方式更改当前区域设置。

// 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 Middleware代码在这里，请随意根据您自己的区域管理进行修改。

本地

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

use Tio\Laravel\Facade as Translation;

Translation::setLocale('fr');

前端本地化

使用此包

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

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

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

注意

• 您可以以多级深度结构化i18n属性，并将子树作为属性传递给每个子组件。
• 它也适用于您组件的服务器端渲染。

使用我们的官方 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库》指南，并使用特殊的init和sync端点。

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

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

许可协议

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。