README

Transmatic是一个Laravel实时机器翻译包，可让您在整个应用程序中实现即时和动态翻译。适用于从简单网站到复杂SaaS平台等各种项目，Transmatic提供定制和灵活性。通过先进的机器翻译，它使您的应用程序在全球范围内可访问。虽然AWS Translate是默认引擎，但此包可以轻松集成其他翻译服务。

常见用例

⚡️ 应用程序自动翻译

使用此包，开发人员可以使用AWS Translate等服务自动将整个应用程序翻译成多种语言。告别为每种语言手动指定翻译，几分钟内即可实现多语言平台。

优势

速度 - 几分钟内翻译应用程序。
自动区域管理 - 包根据提供的文本管理和更新源区域翻译。

👤 个性化用户体验

让用户通过选择他们喜欢的语言来自定义他们的体验。一旦选择，应用程序将动态调整其区域设置。

优势

增强用户体验 - 用用户的母语与之互动。
实时翻译 - 立即适应用户的语言选择。

🏢 SaaS租户特定翻译

通过提供租户特定的翻译来优化SaaS企业的体验。每个租户都可以用他们喜欢的语言查看他们的仪表板。

优势

个性化 - 解决每个租户的语言选择。
互动提升 - 通过展示租户选择的语言的内容来增加互动。

🛍️ 面向全球受众的电子商务

为全球受众定位您的电子商务平台或全球市场。用多种语言提供产品描述、评论等。

优势

全球覆盖范围 - 满足全球受众。
增强销售 - 通过在用户的母语中吸引客户来提高转化率。

安装

首先，通过Composer安装包

composer require andrewdwallo/transmatic

安装包后，运行以下命令

php artisan transmatic:install

设置Transmatic

队列和批量处理设置

此包利用Laravel的队列作业和批量处理功能。具体的设置要求取决于您的Laravel应用程序中配置的队列驱动程序。

数据库队列驱动程序

如果您使用数据库队列驱动程序，则需要在数据库中以下表

jobs：用于管理队列作业。
job_batches：用于批量处理。

如果这些表在数据库中不存在，您可以通过运行以下命令创建它们

php artisan queue:table
php artisan queue:batches-table

创建表后，运行以下命令以迁移它们

php artisan migrate

对于使用其他队列驱动程序（如redis、sqs、beanstalkd等）的用户，请参阅Laravel官方文档中的队列以获取具体的设置说明。

🚧 根据应用程序的要求配置和管理队列系统非常重要。正确的配置确保了包有效地处理后台作业和任务。

AWS Translate集成

默认情况下，该软件包利用AWS Translate。请确保您已按照AWS Service Provider for Laravel文档中的说明设置了必要的配置，并且已设置以下环境变量

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=your-region  # default is us-east-1

这些是AWS SDK用于认证和与AWS服务交互所必需的。一旦设置好这些，您就不需要为AWS Translate做任何事情。

自定义翻译服务集成

虽然AWS Translate是默认的，但Transmatic允许与其他翻译服务集成。要集成，创建一个符合Wallo\Transmatic\Contracts\Translator契约的类，并相应地更新transmatic.php配置文件。

配置概览

提供了一些配置选项，包括设置源语言环境、定义翻译存储方法（缓存或JSON文件）以及指定批量处理行为。请参阅config/transmatic.php文件以获取全面的了解。

使用Transmatic

翻译文本

translate方法提供了一种简单的方法来翻译一段文本。它允许您可选地指定占位符的替换数据以及目标语言环境。如果没有指定目标语言环境，则使用应用程序的当前语言环境。

使用传统参数

use Wallo\Transmatic\Facades\Transmatic;

$translatedText = Transmatic::translate('Hello World', [], 'es'); // Hola Mundo

使用命名参数（PHP 8.0+）

use Wallo\Transmatic\Facades\Transmatic;

$translatedText = Transmatic::translate(text: 'Hello World', to: 'es'); // Hola Mundo

此方法还根据传入的文本更新源语言环境中的翻译，确保存储新字符串以供将来使用。

翻译多个字符串

要一次翻译多个字符串，请使用translateMany方法。此方法接受要翻译的字符串数组以及可选的目标语言环境。如果没有指定，则使用应用程序的当前语言环境。

use Wallo\Transmatic\Facades\Transmatic;

$texts = ['Hello World', 'Goodbye World'];

$translatedTexts = Transmatic::translateMany(texts: $texts, to: 'fr'); // ['Bonjour le monde', 'Au revoir le monde']

与translate方法一样，此方法也将根据传入的文本更新源语言环境中的翻译。

使用翻译占位符

您可以在翻译中使用占位符。为此，请在翻译字符串中使用:placeholder语法。在翻译时，传递一个数组来替换占位符。

use Wallo\Transmatic\Facades\Transmatic;

$translatedText = Transmatic::translate(text: 'Hello :name', replace: ['name' => 'John'], to: 'es'); // Hola John

获取支持的语言环境

要检索支持的语言环境列表，请使用getSupportedLocales方法。此方法将返回应用程序支持的语言环境数组。例如，如果在您的指定文件路径中存储翻译的fr.json文件，则此方法将返回['en', 'fr']。

use Wallo\Transmatic\Facades\Transmatic;

$supportedLocales = Transmatic::getSupportedLocales(); // ['en', 'fr']

获取支持的语言

要检索支持的语言及其对应语言环境列表，请使用getSupportedLanguages方法。此方法返回一个关联数组，其中键是语言环境，值是语言的显示名称。您还可以传递一个显示语言环境作为可选参数，以获取特定语言的名称。如果没有指定显示语言环境，则使用应用程序的当前语言环境。

use Wallo\Transmatic\Facades\Transmatic;

$supportedLanguages = Transmatic::getSupportedLanguages();
// Output: ['en' => 'English', 'fr' => 'French']

$supportedLanguages = Transmatic::getSupportedLanguages(displayLocale: 'fr');
// Output: ['en' => 'Anglais', 'fr' => 'Français']

从语言环境获取语言

您可以使用getLanguage方法从语言环境中获取语言的显示名称。此方法接受您感兴趣的本地和可选的显示本地参数。如果没有指定显示本地，则默认为应用程序的当前本地。

use Wallo\Transmatic\Facades\Transmatic;

$language = Transmatic::getLanguage(locale: 'de'); 
// Output: 'Deutsch'

$language = Transmatic::getLanguage(locale: 'de', displayLocale: 'en'); 
// Output: 'German'

全局助手

对于快速简单的翻译，您可以使用translate()和translateMany()辅助函数。

$translatedText = translate(text: 'Hello World', to: 'es'); // Hola Mundo

$translatedTexts = translateMany(texts: ['Hello World', 'Goodbye World'], to: 'fr'); // ['Bonjour le monde', 'Au revoir le monde']

覆盖全局语言环境

如果您想覆盖所有未指定$to参数的翻译方法的默认语言环境，可以使用setGlobalLocale方法。这将设置全局语言环境覆盖，确保提供的语言环境用作翻译的默认值。

在服务提供程序中设置全局语言环境

在您的服务提供程序的boot方法中，您可以调用setGlobalLocale方法来设置全局语言环境覆盖。

use Wallo\Transmatic\Facades\Transmatic;

public function boot()
{
    Transmatic::setGlobalLocale(locale: 'fr');
}

在设置此全局语言环境后，使用翻译方法时，它们将默认使用此覆盖的语言环境，除非指定了另一个语言环境。

示例

use Wallo\Transmatic\Facades\Transmatic;

Transmatic::setGlobalLocale(locale: 'fr');

$translatedText = Transmatic::translate(text: 'Hello World'); // Bonjour le monde

记住，在翻译方法中指定区域设置将始终优先于全局区域设置覆盖。

use Wallo\Transmatic\Facades\Transmatic;

Transmatic::setGlobalLocale(locale: 'fr');

$translatedText = Transmatic::translate(text: 'Hello World', to: 'es'); // Hola Mundo

处理缺失的翻译

为确保所有翻译都最新，尤其是当某些区域设置存在缺失翻译时，您可以利用处理缺失翻译的功能。这将帮助为除源区域外的所有支持区域生成缺失的翻译。

在服务提供者中使用外观

在您的服务提供者的boot方法中，当调用外观处理缺失翻译时，您有两个选项

指定区域设置

您可以使用processMissingTranslationsFor方法处理特定区域设置列表中的缺失翻译。

use Wallo\Transmatic\Facades\Transmatic;

public function boot()
{
    Transmatic::processMissingTranslationsFor(locales: ['fr', 'de']);
}

处理所有支持区域设置

您可以使用processMissingTranslations方法处理除源区域外所有支持区域的所有缺失翻译。

use Wallo\Transmatic\Facades\Transmatic;

public function boot()
{
    Transmatic::processMissingTranslations();
}

使用Artisan命令

如果您希望手动触发缺失翻译的处理，可以使用控制台命令transmatic:process-missing-translations。此命令将为您提供除源区域外的所有支持区域列表，您可以选择要处理的区域设置。您可以选择选择所有选项一次处理所有区域设置。

此命令在开发期间特别有用，当时您正在为源区域添加新翻译并希望处理所有支持区域的缺失翻译。

php artisan transmatic:process-missing-translations

幕后

管理翻译

当您调用translate或translateMany方法时，Transmatic首先会检查翻译是否已存在于您的应用程序的源区域。如果存在，它将处理并返回指定目标区域的翻译。如果不存在，它将使用新文本更新源区域的翻译，然后继续翻译过程。

Transmatic会检查是否为指定的目标区域运行批处理翻译过程。如果正在运行批处理，则包将根据您的配置从缓存或JSON语言文件中获取翻译。

新翻译与现有翻译

对于新的目标区域，Transmatic通过底层的TranslateService类启动一个队列的批处理翻译过程。这使包能够高效地一次处理大量文本翻译，这得益于队列机制。

对于大多数翻译已经就绪的现有目标区域，使用dispatchSync方法进行即时、同步翻译。

强大源区域的重要性

为了充分利用新目标区域的批处理功能，建议拥有一个内容丰富的源区域语言文件。虽然代码确保在继续翻译之前源区域是最新的，但拥有强大的源区域翻译集可以最大程度地提高新语言的批处理效率。

贡献

感谢您考虑为Transmatic做出贡献！按照以下步骤开始

分支存储库：将此存储库分支到您的GitHub账户。
创建新的Laravel项目：如果您还没有设置Laravel项目，请创建一个。
克隆您分支的存储库：将您分支的Transmatic存储库克隆到您的Laravel应用程序的根目录。

git clone https://github.com/your-github-username/transmatic.git

创建新分支：在'/transmatic'目录内，为您的修复或功能创建一个分支。例如，如果您正在修复错误消息，您可能会将您的分支命名为fix/error-message。

git checkout -b fix/error-message

本地安装包：更新您的应用程序的composer.json文件以包含本地包。使用dev前缀后跟您的分支名称

{
    // ...
    "require": {
        "andrewdwallo/transmatic": "dev-fix/error-message"
    },
    "repositories": [
        {
            "type": "path",
            "url": "transmatic/"
        }
    ],
    // ...
}

更新Composer：运行composer update以在您的Laravel项目中安装本地版本的包。

一旦您完成了更改，请提交它们，然后将它们推送到您的分支，并创建一个拉取请求。您的贡献非常受重视和赞赏！

需要帮助吗？

感谢您对Transmatic的兴趣！无论您是刚开始，发现了错误，还是想提出新功能，以下是您如何获得帮助的方法

🐛 发现了错误吗？

如果您认为您在Transmatic中发现了错误

首先，检查问题部分，看看是否有其他人已经报告了相同的问题。
如果是未报告的错误，请打开一个新问题，尽可能提供详细信息，包括重现问题的步骤。
您可以自由地修复错误！遵循贡献指南开始。

🙋‍♂️ 有问题或功能请求吗？

如果您对如何使用Transmatic或新功能的想法有疑问

首先检查文档，看看您的问题是否已经被解答。
对于具体问题或一般讨论，请访问讨论。
- 有问题？请访问问答。
- 想分享一个想法或功能请求？请在功能请求中分享。

🔐 发现了安全漏洞吗？

安全是首要任务。如果您发现任何有关安全的问题

请不要在GitHub上打开问题。公开披露安全漏洞可能是有害的。
相反，查阅安全策略以获取报告安全漏洞的说明。
我致力于保护用户的安全，并将勤奋地处理有效的安全关注。

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

许可

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

andrewdwallo / transmatic

维护者

详细信息