README

注意：这是新5.x版本的文档。如果您需要旧的4.x版本，请访问4.x分支

由Oscar Otero创建 http://oscarotero.com oom@oscarotero.com (MIT许可证)

Gettext是一个PHP (^7.2)库，用于从PO、MO、PHP、JS文件等导入/导出/编辑gettext。

安装

composer require gettext/gettext

类和函数

此包包含以下类

• Gettext\Translation - 翻译定义
• Gettext\Translations - 翻译集合（在同一域下）
• Gettext\Scanner\* - 扫描文件以提取翻译（php、js、twig模板等）
• Gettext\Loader\* - 从不同格式加载翻译（po、mo、json等）
• Gettext\Generator\* - 将翻译导出到各种格式（po、mo、json等）

使用示例

use Gettext\Loader\PoLoader;
use Gettext\Generator\MoGenerator;

//import from a .po file:
$loader = new PoLoader();
$translations = $loader->loadFile('locales/gl.po');

//edit some translations:
$translation = $translations->find(null, 'apple');

if ($translation) {
    $translation->translate('Mazá');
}

//export to a .mo file:
$generator = new MoGenerator();
$generator->generateFile($translations, 'Locale/gl/LC_MESSAGES/messages.mo');

翻译

Gettext\Translation类存储有关翻译的所有信息：原文、翻译文本、源引用、注释等。

use Gettext\Translation;

$translation = Translation::create('comments', 'One comment', '%s comments');

$translation->translate('Un comentario');
$translation->translatePlural('%s comentarios');

$translation->getReferences()->add('templates/comments/comment.php', 34);
$translation->getComments()->add('To display the amount of comments in a post');

echo $translation->getContext(); // comments
echo $translation->getOriginal(); // One comment
echo $translation->getTranslation(); // Un comentario

// etc...

翻译

Gettext\Translations类存储翻译集合

use Gettext\Translations;

$translations = Translations::create('my-domain');

//You can add new translations:
$translation = Translation::create('comments', 'One comment', '%s comments');
$translations->add($translation);

//Find a specific translation
$translation = $translations->find('comments', 'One comment');

//Edit headers, domain, etc
$translations->getHeaders()->set('Last-Translator', 'Oscar Otero');
$translations->setDomain('my-blog');

加载器

加载器允许从多个格式获取gettext值。例如，加载一个.po文件

use Gettext\Loader\PoLoader;

$loader = new PoLoader();

//From a file
$translations = $loader->loadFile('locales/en.po');

//From a string
$string = file_get_contents('locales2/en.po');
$translations = $loader->loadString($string);

从版本5.7.0开始，包含了一个StrictPoLoader，其解析器与GNU gettext工具更一致，具有相同的期望和失败（有关更多详细信息，请参阅测试）。

• 如果语法有任何错误，它将抛出异常，并显示错误原因以及发生的行/字节。
• 它还可能发出有用的警告，例如，当翻译的复数比所需的更多/更少时，缺少翻译标题，与任何翻译不相关的悬空注释等。
• 由于其严格性和速度（比PoLoader慢约50%），它可能有趣地用作构建系统中的.po检查器。
• 它还实现了以前的翻译注释（例如#| msgid "previous"）和额外的转义（16位Unicode \u、32位Unicode \U、十六进制\xFF和八进制\77）。

使用方法基本上与PoLoader相同

use Gettext\Loader\StrictPoLoader;

$loader = new StrictPoLoader();

//From a file
$translations = $loader->loadFile('locales/en.po');

//From a string
$string = file_get_contents('locales2/en.po');
$translations = $loader->loadString($string);

//Display error messages using "at line X column Y" instead of "at byte X"
$loader->displayErrorLine = true;
//Throw an exception when a warning happens
$loader->throwOnWarning = true;
//Retrieve the warnings
$loader->getWarnings();

此包包含以下加载器

• MoLoader
• PoLoader
• StrictPoLoader

您可以使用加载器和生成器安装其他格式

• Json

生成器

生成器将Gettext\Translations实例导出到任何格式（po、mo等）。

use Gettext\Loader\PoLoader;
use Gettext\Generator\MoGenerator;

//Load a PO file
$poLoader = new PoLoader();

$translations = $poLoader->loadFile('locales/en.po');

//Save to MO file
$moGenerator = new MoGenerator();

$moGenerator->generateFile($translations, 'locales/en.mo');

//Or return as a string
$content = $moGenerator->generateString($translations);
file_put_contents('locales/en.mo', $content);

此包包含以下生成器

• MoGenerator
• PoGenerator

您可以使用加载器和生成器安装其他格式

• Json

扫描器

扫描器允许从不同的来源（如php文件、twig模板、blade模板等）搜索和提取新的gettext条目。与加载器不同，扫描器允许同时提取具有不同域的gettext条目

use Gettext\Scanner\PhpScanner;
use Gettext\Translations;

//Create a new scanner, adding a translation for each domain we want to get:
$phpScanner = new PhpScanner(
    Translations::create('domain1'),
    Translations::create('domain2'),
    Translations::create('domain3')
);

//Set a default domain, so any translations with no domain specified, will be added to that domain
$phpScanner->setDefaultDomain('domain1');

//Extract all comments starting with 'i18n:' and 'Translators:'
$phpScanner->extractCommentsStartingWith('i18n:', 'Translators:');

//Scan files
foreach (glob('*.php') as $file) {
    $phpScanner->scanFile($file);
}

//Get the translations
list('domain1' => $domain1, 'domain2' => $domain2, 'domain3' => $domain3) = $phpScanner->getTranslations();

此包默认不包含任何扫描器。但有一些可以安装

• PHP Scanner
• JS Scanner

合并翻译

您可能需要更新或合并翻译。函数 mergeWith 创建一个新的 Translations 实例，其中包含合并的其他翻译

$translations3 = $translations1->mergeWith($translations2);

但有时这还不够，这就是为什么我们有合并选项，允许配置两个翻译将如何合并。这些选项在 Gettext\Merge 类中定义为常量，如下所示

使用第二个参数来配置合并策略

$strategy = Merge::TRANSLATIONS_OURS | Merge::HEADERS_OURS;

$translations3 = $translations1->mergeWith($translations2, $strategy);

存在一些典型场景，其中之一是最常见的

• 扫描 PHP 模板以寻找需要翻译的项目
• 使用存储在 .po 文件中的翻译来完成这些项目
• 您可能想向 .po 文件中添加新的项目
• 并且也删除那些在 .po 文件中存在但不在模板中（因为它们已被删除）的项目
• 但您想使用新的引用和提取的注释更新一些翻译
• 并保留在 .po 文件中定义的翻译、注释和标志

对于这种场景，您可以使用选项 Merge::SCAN_AND_LOAD 与适合这些需求（扫描新项目并加载 .po 文件）的组合选项。

$newEntries = $scanner->scanFile('template.php');
$previousEntries = $loader->loadFile('translations.po');

$updatedEntries = $newEntries->mergeWith($previousEntries);

未来可能会添加更多常见场景。

相关项目

• gettext-wp-scanner WordPress 代码扫描器，与该库一起使用。

贡献者

感谢所有 贡献者，特别是感谢 @mlocati。

有关最近更改的更多信息，请参阅 CHANGELOG，有关贡献的详细信息，请参阅 CONTRIBUTING。

MIT 许可证 (MIT)。有关更多信息，请参阅 LICENSE。