README

translator

支持复数形式的 PHP 翻译器。

此库与 node 软件包 translator 兼容。

帮助

很抱歉，我再也没有时间维护这个仓库了 :-(

你不想接管它并拯救这个项目吗？

安装

首选方法是使用 composer 安装。

php composer.phar require sakren/translator

字典文件

此翻译器假定以键 -> 翻译的原则工作。为了便于操作，你可以为较小的翻译组拥有许多较小的字典。

这些字典是带有语言代码开头的 json 文件。以下是一些文件的示例。

/app/lang/homepage/en.menu.json
/app/lang/homepage/promo/en.box.json
/app/lang/en.about.json

这里我们有三个字典，两个用于主页，一个用于关于页面，但这些名称完全由你决定。

字典

这是 /app/lang/homepage/promo/en.box.json 字典的示例。

{
	"title": "Promo box",
	"description": "some description",
	"text": "and some really long text",
	"someOtherTextToDisplay": "other boring text"
}

这是字典的最简单示例（也是最愚蠢的）。同样，这些翻译的名称由你决定。

使用

当你有了你的字典后，你可以设置翻译器并开始使用它。

$translator = new \DK\Translator\Translator('/app/lang');
$translator->setLanguage('en');

$message = $translator->translate('homepage.promo.box.text');		// output: and some really long text

你只需要设置语言和基本目录路径。

然后你可以开始翻译。你可以看到要翻译的消息是字典文件的路径，但用点代替斜杠，没有语言代码和 .json 扩展名。

复数形式

已经注册了 138 个复数形式，你可以在此网站上找到它们的列表。如果你缺少某些语言，请提交问题或自己注册。

首先，你必须为你要使用的语言设置复数形式规则。这和 gettext 的复数形式相同。

$translator->addPluralForm(
	'en',				// language code
	2,					// total count of plural forms for this language
	'(n===1) ? 0 : 1'	// decision code. In "n" variable is count of items and it says that if it is 1 item, first (0) form will be used, otherwise second form
);

为了比较，这里有捷克复数形式的示例。

$translator->addPluralForm(
	'cs',
	3,
	'(n===0) ? 2 : ((n===1) ? 0 : ((n>=2 && n<=4) ? 1 : 2))'
);

现在我们必须将复数形式添加到我们的字典中。(/app/lang/homepage/promo/en.box.json)

{
	"cars": [
		"1 car",
		"%count% cars"
	]
}

%count% 将自动替换为项目数。再次比较捷克版本。(/app/lang/homepage/promo/cs.box.json)

{
	"cars": [
		"1 auto",
		"%count% auta",
		"%count% aut"
	]
}

现在你终于可以使用它了。

$message = $translator->translate('homepage.promo.box.cars', 2);		// output: 2 cars

替换

%count% 是替换的基础示例，但你可以创建其他的。例如，你可以设置 %site% 的替换，然后它将自动替换为你的站点名称，这样如果你将来更改它，你只需在一个地方更改。

字典

{
	"info": "web site name: %site%"
}

使用

$translator->addReplacement('site', 'my-site-name.com');
$message = $translator->translate('dictionary.info');		// output: web site name: my-site-name.com

这是持久替换的示例，但你可以为每个翻译创建独立的替换。

字典

{
	"info": "display some random variable: %something%"
}

使用

$message = $translator->translate('dictionary.info', null, array(		// output: display some random variable: 2 books
	'something' => '2 books'
));

如果你不需要传递任何计数（如上面的示例所示），你可以删除第二个参数（null）。

$message = $translator->translate('dictionary.info', array(		// output: display some random variable: 2 books
	'something' => '2 books'
));

翻译名称中

这些替换也可以用在消息名称中。当你有不同用户角色和不同翻译时，这非常有用。然后你可以设置带有名称 role 的替换，并将这些翻译保存到不同的目录中。

en.admin.json

{
	"title": "Page for admin"
}

en.normal.json

{
	"title": "Page for normal user"
}

使用

$translator->addReplacement('role', $user->getRole());
$translator->translate('admin.%role%');

过滤器（例如 markdown）

如果你想在你的翻译中添加一些特殊格式（例如 markdown 语法或其他），你可以添加一个过滤器，它将自动转换所有成功翻译的消息。

$translator->addFilter(function($message) {
	return strrev($message);
});

var_dump($translator->translate('homepage.title'));			// output is reversed title in homepage dictionary

辅助工具

你可以将辅助工具想象成具有可选参数的依赖于翻译的过滤器。

$translator->addHelper('truncate', function($translation, $length) {
	return substr($translation, 0, $length);
});
$translator->addHelper('firstUpper', function($translation) {
	return ucfirst($translation);
});

var_dump($translator->translate('homepage.promo.box.description|truncate:4|firstUpper');		// output: Some

翻译列表

有时你可能想显示文本列表，但又不想为这些名称创建翻译：item1、item2、item3 等。如果你还想添加其他内容，这不是一个好主意。

但是，你可以在你的字典中创建列表，翻译器将返回翻译数组。

字典

{
	"someList": [
		["1st item"],
		["2nd item"],
		["3rd item"],
		["4th item"]
	]
}

使用

$messages = $translator->translate('dictionary.someList');		// output: array(1st item, 2nd item, 3rd item, 4th item)

你也可以使用它来处理复数形式。

字典

{
	"fruits": [
		[
			"1 orange",
			"%count% oranges"
		],
		[
			"1 banana",
			"%count% bananas"
		]
	]
}

使用

$messages = $translator->translate('dictionary.fruits', 6);		// output: array(6 oranges, 6 bananas)

访问精确项

$message = $translator->translate('dictionary.someList[0]');

简短语法

如果你的列表只包含单数形式的翻译，你可以使用简短语法。

{
	"-- myList": [
		"first item",
		"second item",
		"third item"
	]
}

配对列表

如果你有一份标题或标题的列表，以及另一份这些标题的文本列表，你可以让这个翻译器自动将这两个列表合并成一个关联数组。

字典

{
	"titles": [
		["first"],
		["second"]
	],
	"texts": [
		["text for first title"]
		["text for second title"]
	]
}

使用

$translator->translatePairs('dictionary', 'titles', 'texts');

输出

[
	'first' => 'text for first title',
	'second' => 'text for second title'
]

翻译整个数组

当你有一些需要翻译的数组时，你不必自己遍历它。

$messages = array(
    'homepage.promo.box.title',
    'homepage.promo.box.description',
    'homepage.promo.box.text'
);

$result = $translator->translateMap($messages);

如果你的翻译数组只包含一个字典的翻译，你可以设置一种基础路径。

$messages = array(
    'title',
    'description',
    'text'
);

$result = $translator->translateMap($messages, null, null, 'homepage.promo.box.title');

或者使用复数翻译的计数。

$result = $translator->translateMap($messages, 6);

或者使用一些替换。

$result = $translator->translateMap($messages, null, array('type' => 'book'));

临时覆盖语言

在某些情况下，你可能需要获取不同语言的翻译。

$translator = new \DK\Translator\Translator('/app/lang');
$translator->setLanguage('en');

$message = $translator->translate('cs|homepage.title');

现在在 message 变量中将是 czech 语言中 homepage.title 的翻译。

字典中的注释

你可以在你的字典中写入一些注释。这些注释必须包含在 # 中。

{
	"message": [
		"# this message will be displayed in home page #",
		 "translation of message"
	]
}

或者使用列表

{
	"list": [
		"# this is list of some items #",
		[
			"# first item in list #",
			"first"
		],
		[
			"# second item in list #",
			"second"
		]
	]
}

与 Nette 框架一起使用

如果你想使用这个翻译器与 nette，请使用 sakren/nette-translator 库。

变更日志

1.7.1
- 移至 Carrooi 组织下
- 弃用包
1.7.0
- 优化消息解析
- 添加翻译辅助工具
- 添加方法 getLastTranslated()
1.6.4
- 方法 getMessageInfo() 现在是公共的
1.6.3
- 方法 findTranslation() 现在是公共的
1.6.2
- 添加方法 getTranslated() 和 getUntranslated()
- 在加载器中添加方法 save()（为未来的改进做准备）
1.6.1
- 一些内部更改
1.6.0
- 优化
- 添加徽章和 travis
- 在干净安装后失败的测试
- 从配置文件创建翻译器（用于API）
- 添加了 hasTranslation 方法
- 临时覆盖语言的选项
- 添加了过滤器
1.5.0
- 添加了 translateMap 方法
1.4.0
- 在 translate 方法中访问列表中的项目
1.3.2
- Translate 方法：可以作为第二个参数传递参数
1.3.1
- 添加了一些信息
1.3.0
- 添加了测试
- 添加了编写列表的简短语法
- 添加了对注释的支持
- 移除了 Nette 支持（将在另一个包中）
1.2.2
- 优化了复数形式
- 替换没有应用于消息（巨大错误，抱歉）
1.2.1
- 消息中的替换
1.2.0
- 添加了 translatePairs 方法

carrooi / translator

维护者

详细信息