README

与 Sami 工具配合使用，从 PhpDocs 生成多语言 HTML API 文档。

翻译例程由 Gettext 格式 和其 PHP 实现 提供支持。

基本用法是准备 Sami 配置 PHP 文件...

// include all necessary dependencies
require_once __DIR__ . '/vendor/autoload.php';

use Sami\Sami;
use Symfony\Component\Finder\Finder;
use umi\sami\translator\TranslatorPlugin;

// create any files iterator you like
$iterator = Finder::create()
    ->in(getcwd())
    ->exclude('.git')
    ->exclude('.idea')
    ->exclude('vendor')
    ->exclude('tests')
    ->exclude('docs')
    ->name('*.php');

// tune up generation process
$options = [
    // where to look your php source code
    // specify version placeholder for separate HTML output
    'build_dir' => getcwd() . '/docs/build/%version%',
    // to faster cache deletion ;)
    'cache_dir' => getcwd() . '/docs/cache/%version%',
    // this is required option
    'default_opened_level' => 2,
];

// pass iterator & options to Sami tool instance
$sami = new Sami($iterator, $options);

// now power it up with i18n with direct instantiation
$sami[TranslatorPlugin::ID] = new TranslatorPlugin('ru', $sami, [
    // skip phpDocs containing stub docs
    'ignoreDocPatterns'  => [
        '/@inheritdoc/',
        '/@copyright/'
    ],
    // where we keep our .po + .pot + .mo translation files
    'translationsPath'   => 'any/path/you/want/to/keep/gettext/files',

    // path also can be extended with custom version subdir
    // (by default version dir will be appended to translations path to avoid data losing)
    //'translationsPath' => 'D:/gettext-repo/%version%/subdir',

    // path can be relative to build dir, to keep translations together with API build
    //'translationsPath' => '%build%/translations/', // add %version% anywhere, to your taste

    // whether to add PhpDoc'ed code as translation comment, for sensible human-translating
    'useContextComments' => true,

]);

return $sami;

...然后执行 Sami 控制台工具，传入此 PHP 配置文件的位置

sami.php update /path/to/config.php

首次翻译

如果您之前没有翻译过源代码且没有 .pot 文件，翻译插件将根据特殊标志生成它

$sami[TranslatorPlugin::ID] = new TranslatorPlugin('ru', $sami, [
    // ...
    // create non-existent & update existing .po + .pot file sets
    'translateOnly' => false,
]);

现在在 translationsPath 中创建了 .po+.pot 文件对。打开您的 PoEdit 工具并开始国际化工作！

保存翻译结果并生成 .mo 文件后，您可以再次运行 Sami 以刷新 HTML 构建

sami.php update /path/to/config.php

消息键模式

最初，翻译器只能通过字符大小直接索引 phpdoc 消息，用于字符大小翻译工作流程。

在 v 0.2 之后，我们引入了第二种构建键值消息对的方法：通过签名

$sami[TranslatorPlugin::ID] = new TranslatorPlugin('ru', $sami, [
    // ...
    // use signatures
    'messageKeysStrategy' => TranslatorPlugin::USE_SIGNATURES_AS_KEYS
]);

之前的策略，USE_PHPDOCS_AS_KEYS 仍然是默认设置。