README

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

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

安装

使用 composer (推荐)

composer require gettext/gettext

如果您在项目中不使用 composer，您必须下载并将此软件包放置在您的项目目录中。您还需要安装 gettext/languages。然后，在任何 PHP 代码位置包含两个项目的自动加载器。

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');

如果您想在您的 PHP 模板中使用这些翻译而不使用 gettext 扩展

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 comments', '%s comments');

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

//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 = $translatons->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。

捐赠

如果此库对您有帮助，请考虑向作者捐赠。

请我喝杯啤酒 🍺

提前感谢！