README

这是由 Michael Babker 创建的存档存储库的分支。由于 Mautic 使用此库，因此我们决定维护它。

Transifex API 包

Transifex API 包 是访问 Transifex API 的 PHP 客户端。

需求

PHP 7.4 或更高版本
任何 PSR-17 兼容工厂
任何 PSR-18 兼容 HTTP 客户端

安装

通过 GIT 安装

从 GIT 获取源代码

git clone git://github.com/mautic/Transifex-API.git

通过 Composer 安装

要将此包包含到您的 Composer 项目中，请在命令行中运行以下命令

composer require mautic/transifex

文档

Transifex API 包提供了与 Transifex API 交互的 PHP 接口。

基本使用

与 Transifex 包交互的主要接口是 Transifex 类。此类作为 API 工厂，允许开发者管理 API 对象和 HTTP 连接器使用的选项，以及检索 API 对象的实例。要创建 Transifex 对象，您只需要用适当的依赖项实例化它。

use Mautic\Transifex\ApiFactory;
use Mautic\Transifex\Config;
use Mautic\Transifex\Transifex;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Http\Message\UriFactoryInterface;

$client = new ClientInterface(); // or any PSR-18 HTTP client
$requestFactory = new RequestFactoryInterface(); // or any PSR-17 Request factory
$streamFactory = new StreamFactoryInterface(); // or any PSR-17 Stream factory
$uriFactory = new UriFactoryInterface(); // or any PSR-17 URI factory
$config = new Config();
$config->setApiToken('some-api-token');
$config->setOrganization('some-organization');
$config->setProject('some-project');
$transifex = new Transifex($client, $requestFactory, $streamFactory, $uriFactory, $config);

请参阅 Transifex 文档了解如何获取 API 令牌。

也可以从环境变量创建 Config 对象

use Mautic\Transifex\Config;
putenv('TRANSIFEX_API_TOKEN=some-api-token');
putenv('TRANSIFEX_ORGANIZATION=some-organization');
putenv('TRANSIFEX_PROJECT=some-project');
$config = Config::fromEnv();

要检索 API 对象的实例，您将使用 get() 方法。API 对象的名称基于 Transifex API 文档中记录的部分。要检索可以与 "resources" API 部分交互的对象，您将使用以下代码

use \Mautic\Transifex\Connector\Resources;
$resources = $transifex->getConnector(Resources::class);
\assert($resources instanceof Resources);

API 响应

此包返回由底层 PSR-18 HTTP 客户端创建的与 PSR-7 兼容的响应。

此包不会捕获 HTTP 客户端抛出的异常，因此实现此包的用户应实现适当的错误处理机制。

当响应码大于400时，将抛出 Mautic\Transifex\Exception\ResponseException 异常。错误信息包含URI、请求和响应，这简化了调试。可以从这个异常中检索请求和响应对象。

资源

资源是应该被翻译的基本文件。

获取以下示例的资源连接器如下

use Mautic\Transifex\Connector\Resources;

$resources = $transifex->getConnector(Resources::class);
\assert($resources instanceof Resources);

获取所有资源

文档：[https://developers.transifex.com/reference/get_resources](https://developers.transifex.com/reference/get_resources)

$response = $resources->getAll();
$body     = json_decode($response->getBody()->__toString(), true);

创建资源

这是一个同步操作，所以您可以立即获得响应。但是，您需要另一个请求来上传内容到该资源。请参阅文档中的示例响应。

要获取可用的i18n格式列表（第三个参数），请触发此端点。

$response = $resources->create('Resource A', 'resource-a', 'INI');
$body     = json_decode($response->getBody()->__toString(), true);

上传资源内容

这是一个异步操作，所以第一个请求只是将任务添加到队列并返回一个唯一ID。请参阅文档。然后我们必须轮询另一个端点以获取此任务的状态。

use Mautic\Transifex\Promise;
use Mautic\Transifex\Exception\ResponseException;
use Psr\Http\Message\ResponseInterface;

$response = $resources->uploadContent('resource-a', "something=\"Something\"\nsomething.else=\"Something Else\"\n");
$promise  = $transifex->getApiConnector()->createPromise($response);
$promises = new \SplQueue();
$promise->setFilePath('/some/file.ini'); // In the real world it is useful to map your file to this promise. Useful for later processing.
$promises->enqueue($promise); // In the real world, there would be multiple promises.
usleep(500000); // Give Transifex a 1/2 second so we make 1 request instead of 2.
$transifex->getApiConnector()->fulfillPromises(
    $promises,
    function (ResponseInterface $response, Promise $promise) {
        echo "Resource for {$promise->getFilePath()} was uploaded successfully";
    },
    function (ResponseException $exception, Promise $promise) {
        echo "Resource upload for {$promise->getFilePath()} failed with {$exception->getMessage()}";
    }
);

轮询承诺状态会每0.5秒自动发生。

由于获取承诺状态是异步的，且处理承诺的顺序不确定，因此为您提供了回调，以在成功和失败状态上做出反应。另一个好处是，直到所有承诺都解决，不会阻塞进一步的加工。

删除资源

文档：[https://developers.transifex.com/reference/delete_resources-resource-id](https://developers.transifex.com/reference/delete_resources-resource-id)

$response = $resources->delete('resource-a');

翻译

翻译将资源内容翻译成其他语言。

获取以下示例的翻译连接器如下

use Mautic\Transifex\Connector\Translations;

$translations = $transifex->getConnector(Translations::class);
\assert($translations instanceof Translations);

上传翻译

上传翻译也是异步的。工作流程与下载翻译或资源类似。

$response = $translations->upload(self::RESOURCE_SLUG, 'cs', "something=\"Něco\"\n");
$promise  = $transifex->getApiConnector()->createPromise($response);
$promises = new SplQueue();
$promise->setFilePath('/some/file.ini'); // In the real world it is useful to map your file to this promise. Useful for later processing.
$promises->enqueue($promise); // In the real world, there would be multiple promises.
usleep(500000); // Give Transifex a 1/2 second so we make 1 request instead of 2.
$transifex->getApiConnector()->fulfillPromises(
    $promises,
    function (ResponseInterface $response, Promise $promise) {
        echo "Translation for {$promise->getFilePath()} was uploaded successfully";
    },
    function (ResponseException $exception, Promise $promise) {
        echo "Translation upload for {$promise->getFilePath()} failed with {$exception->getMessage()}";
    }
);

下载翻译

这是您需要获取翻译者工作的端点。也是一个异步操作。查看文档。它使用与其他相同的模式。

$response = $translations->download(self::RESOURCE_SLUG, 'cs');
$promise  = $transifex->getApiConnector()->createPromise($response);
$promises = new SplQueue();
$promise->setFilePath('/some/file.ini'); // In the real world it is useful to map your file to this promise. Useful for later processing.
$promises->enqueue($promise); // In the real world, there would be multiple promises.

usleep(500000); // Give Transifex a 1/2 second so we make 1 request instead of 2.


// Assert that the translation content was downloaded successfully.
$transifex->getApiConnector()->fulfillPromises(
    $promises,
    function (ResponseInterface $response) use (&$successCounter, &$translationContent) {
        $translationContent = $response->getBody()->__toString();
        echo "Translation for {$promise->getFilePath()} was downloaded successfully. Here's the content:\n{$translationContent}";
    },
    function (ResponseException $exception) {
        echo "Translation download for {$promise->getFilePath()} failed with {$exception->getMessage()}";
    }
);

测试

有一个功能测试可以运行所有覆盖的API请求对现有的Transifex项目。它需要一个配置来连接到该项目。复制phpunit.xml.dist文件并将其重命名为phpunit.xml。这创建了一个默认PHPUNIT配置的重写。填写组织、项目和API令牌值。测试项目必须有可用的cs翻译。

要运行实时测试，请执行composer test -- --testsuite=Functional。要运行单元测试，请执行composer test -- --testsuite=Unit。

运行整个测试套件：composer test。运行静态分析检查：composer phpstan。运行代码风格检查：composer cs。修复代码风格问题：composer fixcs。

mautic / transifex

维护者

详细信息