README

这是由 Michael Babker 的存档仓库 archived repository 的分支。Autoborna 使用此库，因此我们决定维护它。

Transifex API 包

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

要求

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

安装

通过 GIT 安装

从 GIT 获取源代码

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

通过 Composer 安装

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

composer require autoborna/transifex

文档

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

基本用法

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

use Autoborna\Transifex\ApiFactory;
use Autoborna\Transifex\Config;
use Autoborna\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 Autoborna\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 \Autoborna\Transifex\Connector\Resources;
$resources = $transifex->getConnector(Resources::class);
\assert($resources instanceof Resources);

API 响应

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

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

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

资源

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

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

use Autoborna\Transifex\Connector\Resources;

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

获取所有资源

文档：https://developers.transifex.com/reference/get_resources

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

创建资源

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

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

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

上传资源内容

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

use Autoborna\Transifex\Promise;
use Autoborna\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

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

翻译

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

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

use Autoborna\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()}";
    }
);

测试

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

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

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