README

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

Gettext是一个PHP (>=5.4)库，用于导入/导出/编辑PO、MO、PHP、JS文件等格式的gettext。

安装

使用composer（推荐）

composer require gettext/gettext

如果你在项目中没有使用composer，你必须下载并将此包放置在你的项目目录中。你还需要安装gettext/languages。然后，在任何地方包含这两个项目的自动加载器。

include_once "libs/gettext/src/autoloader.php";
include_once "libs/cldr-to-gettext-plural-rules/src/autoloader.php";

类和函数

此包包含以下类

• Gettext\Translation - 翻译定义
• Gettext\Translations - 翻译集合
• Gettext\Extractors\* - 从各种来源（po、mo、php、js等）导入翻译
• Gettext\Generators\* - 将翻译导出到各种格式（po、mo、php、json等）
• Gettext\Translator - 在你的PHP模板中使用翻译而不是gettext扩展
• Gettext\GettextTranslator - 使用gettext扩展

使用示例

use Gettext\Translations;

//import from a .po file:
$translations = Translations::fromPoFile('locales/gl.po');

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

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

//export to a php array:
$translations->toPhpArrayFile('locales/gl.php');

//and to a .mo file
$translations->toMoFile('Locale/gl/LC_MESSAGES/messages.mo');

如果你想在不使用gettext扩展的情况下在你的PHP模板中使用这些翻译

use Gettext\Translator;

//Create the translator instance
$t = new Translator();

//Load your translations (exported as PhpArray):
$t->loadTranslations('locales/gl.php');

//Use it:
echo $t->gettext('apple'); // "Mazá"

//If you want use global functions:
$t->register();

echo __('apple'); // "Mazá"

如果想使用gettext扩展来使用这些翻译

use Gettext\GettextTranslator;

//Create the translator instance
$t = new GettextTranslator();

//Set the language and load the domain
$t->setLanguage('gl');
$t->loadDomain('messages', 'Locale');

//Use it:
echo $t->gettext('apple'); // "Mazá"

//Or use the gettext functions
echo gettext('apple'); // "Mazá"

//If you want use the global functions
$t->register();

echo __('apple'); // "Mazá"

//And use sprintf/strtr placeholders
echo __('Hello %s', 'world'); //Hello world
echo __('Hello {name}', ['{name}' => 'world']); //Hello world

使用此库提供的函数（__()代替_()或gettext()）的好处是

• 你使用的是相同的函数，无论翻译是由gettext扩展还是其他方法提供的。
• 你可以更容易地使用变量，因为包含了sprintf功能。例如：__('Hello %s', 'world')代替sprintf(_('Hello %s'), 'world')。
• 如果你将第二个参数作为数组，你也可以使用命名占位符。例如：__('Hello %name%', ['%name%' => 'world'])代替strtr(_('Hello %name%'), ['%name%' => 'world'])。

翻译

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

// __construct($context, $original, $plural)
$translation = new Gettext\Translation('comments', 'One comment', '%s comments');

$translation->setTranslation('Un comentario');
$translation->setPluralTranslation('%s comentarios');

$translation->addReference('templates/comments/comment.php', 34);
$translation->addComment('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类存储翻译集合

$translations = new Gettext\Translations();

//You can add new translations using the array syntax
$translations[] = new Gettext\Translation('comments', 'One comment', '%s comments');

//Or using the "insert" method
$insertedTranslation = $translations->insert('comments', 'One comment', '%s comments');

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

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

提取器

提取器允许从任何来源获取gettext值。例如，扫描一个.po文件

$translations = new Gettext\Translations();

//From a file
Gettext\Extractors\Po::fromFile('locales/en.po', $translations);

//From a string
$string = file_get_contents('locales2/en.po');
Gettext\Extractors\Po::fromString($string, $translations);

使用提取器的最佳方式是使用Gettext\Translations的魔法方法

//Create a Translations instance using a po file
$translations = Gettext\Translations::fromPoFile('locales/en.po');

//Add more messages from other files
$translations->addFromPoFile('locales2/en.po');

可用的提取器如下

生成器

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

//Save to a file
Gettext\Generators\Po::toFile($translations, 'locales/en.po');

//Return as a string
$content = Gettext\Generators\Po::toString($translations);
file_put_contents('locales/en.po', $content);

与提取器一样，使用生成器的最佳方式是使用Gettext\Translations的魔法方法

//Extract messages from a php code file
$translations = Gettext\Translations::fromPhpCodeFile('templates/index.php');

//Export to a po file
$translations->toPoFile('locales/en.po');

//Export to a po string
$content = $translations->toPoString();
file_put_contents('locales/en.po', $content);

可用的生成器如下

翻译器

Gettext\Translator类实现了PHP中的gettext函数。如果你没有PHP的本地gettext扩展或想要避免与之相关的问题，这很有用。你可以从PHP数组文件或使用Gettext\Translations实例加载数据。

use Gettext\Translator;

//Create a new instance of the translator
$t = new Translator();

//Load the translations using any of the following ways:

// 1. from php files (generated by Gettext\Extractors\PhpArray)
$t->loadTranslations('locales/gl.php');

// 2. using the array directly
$array = include 'locales/gl.php';
$t->loadTranslations($array);

// 3. using a Gettext\Translations instance (slower)
$translations = Gettext\Translations::fromPoFile('locales/gl.po');
$t->loadTranslations($translations);

//Now you can use it in your templates
echo $t->gettext('apple');

GettextTranslator

类 Gettext\GettextTranslator 使用了 gettext 扩展。它很有用，因为它结合了使用真实 gettext 函数的性能，同时具有与 Translator 类相同的 API，因此您可以根据环境切换到任意一种翻译器，而无需修改您的应用程序代码。

use Gettext\GettextTranslator;

//Create a new instance
$t = new GettextTranslator();

//It detects the environment variables to set the locale, but you can change it:
$t->setLanguage('gl');

//Load the domains:
$t->loadDomain('messages', 'project/Locale');
//this means you have the file "project/Locale/gl/LC_MESSAGES/messages.po"

//Now you can use it in your templates
echo $t->gettext('apple');

全局函数

为了简化您在 PHP 模板中使用翻译，您可以使用提供的函数

//Register the translator to use the global functions
$t->register();

echo __('apple'); // it's the same than $t->gettext('apple');

您可以使用 PhpCode 提取器扫描包含这些函数的 PHP 文件并提取值

<!-- index.php -->
<html>
	<body>
		<?= __('Hello world'); ?>
	</body>
</html>

合并翻译

要处理不同的翻译，您可能希望将它们合并到一个单独的文件中。有两种方法可以实现这一点

最简单的方法是添加新的翻译

use Gettext\Translations;

$translations = Translations::fromPoFile('my-file1.po');
$translations->addFromPoFile('my-file2.po');

更高级的方法是合并两个 Translations 实例

use Gettext\Translations;

//Create a new Translations instances with our translations.

$translations1 = Translations::fromPoFile('my-file1.po');
$translations2 = Translations::fromPoFile('my-file2.po');

//Merge one inside other:
$translations1->mergeWith($translations2);

//Now translations1 has all values

mergeWith 的第二个参数定义了合并的方式。使用 Gettext\Merge 常量来配置合并

示例

use Gettext\Translations;
use Gettext\Merge;

//Scan the php code to find the latest gettext translations
$phpTranslations = Translations::fromPhpCodeFile('my-templates.php');

//Get the translations of the code that are stored in a po file
$poTranslations = Translations::fromPoFile('locale.po');

//Merge the translations from the po file using the references from `$phpTranslations`:
$translations->mergeWith($poTranslations, Merge::REFERENCES_OURS);

//Now save a po file with the result
$translations->toPoFile('locale.po');

注意，如果第二个参数未定义，则默认值为 Merge::DEFAULTS，这相当于 Merge::ADD | Merge::HEADERS_ADD。

从 CLI 使用

有一个 Robo 任务可以从命令行界面使用这个库：https://github.com/oscarotero/GettextRobo

在浏览器中使用

如果您想在浏览器中使用您的翻译，有一个 JavaScript 翻译器：https://github.com/oscarotero/gettext-translator

第三方包

Twig 集成

• jaimeperez/twig-configurable-i18n
• cemerson/translator-twig-extension

框架集成

• Laravel 5
• CakePHP 3
• Symfony 2

添加您的包

贡献者

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

捐赠

如果这个库对您有用，请考虑向作者捐赠。

请我喝杯啤酒 🍺

提前感谢！