README

简介

Laravel Deepl是一个集成了DeepL API的Laravel扩展包。它允许您使用DeepL服务翻译文本、文档、管理术语表以及执行其他有用任务。

要求

在安装和使用此扩展包之前，请确保您的环境满足以下最低要求

PHP 8.2或更高版本
Laravel 11.0或更高版本
GuzzleHTTP 7.0或更高版本

这些版本是确保与扩展包及其提供的功能兼容所必需的。在集成此扩展包之前，请确保您的项目正在运行这些版本或更高版本。

安装

您可以通过Composer安装此扩展包

composer require pavelzanek/laravel-deepl

配置

要发布配置文件，请运行

php artisan vendor:publish --tag=laravel-deepl-config

这将在config/laravel-deepl.php中创建一个文件，您可以在其中设置DeepL API密钥和其他配置选项。

环境变量

将您的DeepL API密钥添加到您的.env文件中

DEEPL_API_KEY=your-deepl-api-key

您可能还想设置的其它环境变量

DEEPL_API_TYPE=free # or pro
DEEPL_DEFAULT_SOURCE_LANG=en
DEEPL_DEFAULT_TARGET_LANG=cs
DEEPL_API_VERSION=v2
DEEPL_RETRY_ON_FAILURES=3
DEEPL_TIMEOUT=30
DEEPL_ENABLE_TRANSLATION_CACHE=true

用法

用法选项：门面 vs. 客户端

该扩展包提供了两种与DeepL API交互的主要方式：使用门面或直接使用DeeplClient类。这种灵活性允许您选择最适合您的应用程序架构的方法。

文本翻译

您可以使用提供的客户端轻松翻译文本

use PavelZanek\LaravelDeepl\Facades\Deepl;

$translatedText = Deepl::textTranslation('Hello, world!')
    ->sourceLang('en')
    ->targetLang('de')
    ->getTranslation();

echo $translatedText; // Outputs: Hallo, Welt!

缓存翻译

该扩展包包含一个缓存机制，将翻译存储在数据库中以优化性能并减少对DeepL的API调用次数。这在使用相同文本多次翻译或处理大量文本时特别有用。

运行迁移

在使用缓存功能之前，您需要发布并运行创建数据库中translations表的迁移

php artisan vendor:publish --tag=laravel-deepl-migrations
php artisan migrate

这将创建存储翻译的必要表。

缓存工作原理

在您请求翻译时，该扩展包会检查翻译是否已存在于数据库中，然后再向DeepL发出API调用。这由useCache属性控制，默认情况下是启用的。

如果缓存中存在翻译：则返回缓存中的翻译，避免API调用。
如果缓存中不存在翻译：则向DeepL发出API调用，并将翻译结果存储在数据库中以供未来请求使用。

示例用法

use PavelZanek\LaravelDeepl\DeeplClient;

$client = new DeeplClient();

$translatedText = $client->textTranslation('Hello, world!')
    ->sourceLang('en')
    ->targetLang('de')
    ->getTranslation();

echo $translatedText; // Outputs: Hallo, Welt!

在此示例中，“Hello, world!”从英语翻译成德语，要么从缓存中检索，要么如果没有缓存，则从DeepL获取并存储在缓存中以供将来使用。

禁用缓存

如果您需要绕过缓存并始终进行新鲜API调用，可以使用withoutCache方法

$translatedText = $client->textTranslation('Hello, world!')
    ->sourceLang('en')
    ->targetLang('de')
    ->withoutCache()  // Disables cache usage
    ->getTranslation();

自定义缓存行为

缓存机制使用Translation模型来存储翻译的文本。缓存由配置文件中的enable_translation_cache选项控制（config/laravel-deepl.php），默认设置为true。您可以通过将该选项设置为false来全局禁用缓存

// config/laravel-deepl.php

return [
    // ...
    'enable_translation_cache' => false,
    // ...
];

禁用此选项意味着每次翻译请求都会导致向DeepL发出API调用，这可能会增加您的API使用成本。

缓存的好处

性能：通过重用翻译来减少对DeepL API的负载。
成本节省：有助于最小化API调用次数，从而降低潜在成本。
灵活性：在需要时，可以轻松绕过或禁用缓存以获取新鲜翻译。

缓存功能是优化您的应用程序本地化工作流程的强大工具，确保翻译既快速又经济。

文档翻译

您还可以翻译文档

$documentClient = Deepl::documentTranslation();
$uploadResponse = $documentClient->uploadDocument('path/to/document.pdf', 'de');

$status = $documentClient->getDocumentStatus($uploadResponse['document_id'], $uploadResponse['document_key']);

if ($status['status'] === \PavelZanek\LaravelDeepl\Enums\V2\DocumentStatus::DONE->value) {
    $translatedDocument = $documentClient->downloadTranslatedDocument($uploadResponse['document_id'], $uploadResponse['document_key']);
    file_put_contents('path/to/translated-document.pdf', $translatedDocument);
}

术语管理

您可以创建、检索和删除术语表

$glossaryClient = Deepl::glossary();

$glossary = $glossaryClient->createGlossary(
    'My Glossary',
    'en',
    'de',
    [
        'hello' => 'hallo',
        'world' => 'welt',
    ]
);

$glossaryDetails = $glossaryClient->getGlossary($glossary['glossary_id']);

$glossaryClient->deleteGlossary($glossary['glossary_id']);

语言支持

您可以列出所有支持的语言

$sourceLanguages = Deepl::languages()->getSourceLanguages();
$targetLanguages = Deepl::languages()->getTargetLanguages();

使用限制

您可以从DeepL API检索当前使用情况和配额信息，以监控您的翻译使用情况

$usage = Deepl::usage()->getUsage();

这将返回一个包含您的API使用详情的数组，包括翻译的字符数和其他相关配额限制。您可以使用这些信息确保您不会超过API限制。

此外，该包提供了一个方便的Artisan命令，允许您从命令行直接检索和显示此信息

php artisan deepl:usage

此命令将以表格格式显示当前计费期间翻译的字符数和相应的账户限制

+-----------------------------------------------------+--------------+
| Usage & quota                                       | Value        |
+-----------------------------------------------------+--------------+
| Translated characters in the current billing period | 1,234,567    |
| Character limits in the current billing period      | 2,000,000    |
+-----------------------------------------------------+--------------+

翻译本地化文件

该包包括一个方便的Artisan命令，用于使用DeepL API翻译Laravel本地化文件。这允许您快速将应用程序的语言文件从一种语言翻译到另一种语言。

命令语法

您可以使用以下方式使用此命令

php artisan deepl:translate {file} --sourceLang=en --targetLang=cs

file：要翻译的本地化文件的路径
--sourceLang：源语言代码（默认为en）
--targetLang：目标语言代码（默认为cs）

示例

要将文件从英语翻译成捷克语，您可以运行

php artisan deepl:translate resources/lang/en/messages.php --sourceLang=en --targetLang=cs

这将创建一个翻译文件在resources/lang/cs/messages.php，保留原始文件的结构和格式。

处理JSON和PHP文件

该命令支持JSON和PHP本地化文件。它将根据文件扩展名自动检测文件类型，并相应地处理翻译。

对于JSON文件：翻译以JSON格式保存，键和值得到保留
对于PHP文件：翻译以PHP数组语法保存，键和值得到保留

占位符

该命令足够智能，可以处理本地化字符串中的占位符（例如，:attribute）。它确保这些占位符在翻译过程中保持不变，从而保留应用程序的完整性。

目录创建

如果目标目录不存在，则命令将自动创建它，确保翻译文件保存在正确的位置。

辅助工具

枚举

此包提供了一组枚举（枚举），以简化并标准化与DeepL API交互时某些选项和参数的使用。这些枚举有助于确保您的代码保持一致，并减少出错的可能性。

可用枚举

以下是包中包含的一些枚举

DocumentStatus：表示文档翻译的状态。
- DocumentStatus::DONE
- DocumentStatus::TRANSLATING
Formality：允许您控制翻译文本的正式程度。
- Formality::DEFAULT
- Formality::MORE
- Formality::LESS
- Formality::PREFER_MORE
- Formality::PREFER_LESS
PreserveFormatting：控制是否在翻译中保留原始格式。
- PreserveFormatting::DISABLED
- PreserveFormatting::ENABLED
SourceLanguage：列出可用的源语言。
- 包括如SourceLanguage::ENGLISH、SourceLanguage::GERMAN、SourceLanguage::FRENCH等语言。
- 特殊值：SourceLanguage::AUTOMATIC，让DeepL自动检测源语言。
SplitSentences：配置翻译过程中句子应该如何分割。
- SplitSentences::NONE
- SplitSentences::DEFAULT
- SplitSentences::NO_NEWLINES
TargetLanguage：列出可用的目标语言。
- 包括如下语言：TargetLanguage::ENGLISH_BRITISH、TargetLanguage::GERMAN、TargetLanguage::SPANISH等。

示例用法

您可以使用这些枚举来提高代码可读性并减少错误机会。

use PavelZanek\LaravelDeepl\Facades\Deepl;
use PavelZanek\LaravelDeepl\Enums\V2\Formality;
use PavelZanek\LaravelDeepl\Enums\V2\SourceLanguage;
use PavelZanek\LaravelDeepl\Enums\V2\TargetLanguage;

$translatedText = Deepl::textTranslation('How are you today?')
    ->sourceLang(SourceLanguage::ENGLISH->value)
    ->targetLang(TargetLanguage::GERMAN->value)
    ->formality(Formality::PREFER_LESS->value)
    ->getTranslation();

echo $translatedText; // Outputs: Wie geht es dir heute?

测试

要运行测试，请使用：

composer test

测试套件涵盖了多个方面，包括：

翻译缓存和检索。
使用外观（Facade）和DeeplClient进行翻译。
JSON和PHP语言文件的翻译。
处理边缘情况和错误场景。

代码风格检查

您可以使用PHPStan来确保代码质量。

composer lint

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件zanek.pavel@gmail.com联系，而不是使用问题跟踪器。

许可证

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

赵伟泽内克 / laravel-deepl

维护者

详细信息

README

简介

要求

安装

配置

环境变量

用法

用法选项：门面 vs. 客户端

文本翻译

缓存翻译

运行迁移

缓存工作原理

示例用法

文档翻译

术语管理

语言支持

使用限制

翻译本地化文件

命令语法

示例

处理JSON和PHP文件

占位符

目录创建

辅助工具

枚举

可用枚举

示例用法

测试

代码风格检查

更新日志

贡献

安全性

许可证