README

Mirza Yandex Translator For Laravel

Mirza Translator 允许您轻松使用 Yandex.Translate API 进行文本翻译和操作。

目录

1. 快速入门
2. 快速使用指南
3. 文档
4. 方法
5. Blade 指令
6. 问题 & 建议
7. 许可

快速入门

让我们快速设置，只需要三个简单步骤！

• 通过终端/cmd导航到您的 Laravel 安装文件夹，并运行 composer require yak0d3/Mirza_Yandex_Translator 或手动将 "yak0d3/Mirza_Yandex_Translator": "^1.0.0" 添加到 composer.json。

• 使用以下方法之一发布配置文件

  1. 运行 php artisan vendor:publish --provider="yak0d3\Mirza_Yandex_TranslatorT\MirzaServiceProvider"
  2. 运行 php artisan vendor:publish 并输入 yak0d3\Mirza_Yandex_TranslatorT\MirzaServiceProvider 后面的数字，然后按 Enter

• 将环境变量添加到您的 .env 文件中，名称为 YANDEX_API，并将其值设置为您的 Yandex.Translate API 密钥。（例如 YANDEX_API=MY_YANDEX_API_KEY）

注意：您可以从 Yandex.Translate 开发者仪表板 获取免费的 API 密钥。

快速使用指南

快速使用指南仅用于解释此包的基本用法，有关方法列表及其相关信息（参数、返回类型等），请跳转到方法部分或跳转到指令部分以查看可用的 blade 指令。

• 检测语言
  Mirza::detectLanguage('Welcome');
  输出： en

• 翻译文本
  Mirza::translate('Hello','es');
  输出： "Hola"

• 翻译到多种语言
  Mirza::translateTo('Hello World!',['es', 'tr', 'fr'])
  
  输出

   {
    "originalText": "Hello World!",
    "originalLanguage": "en",
    "text": {
    "es": "Hola Mundo!",
    "tr": "Merhaba D\u00fcnya!",
    "fr": "Bonjour Tout Le Monde!"
    }
   }

注意：您可以使用 json_decode 函数解码此字符串。

• 翻译文本数组
  $textArray = ['Hello','My Dear','Friend'];
Mirza::translateArray($textArray,'fr');
  输出

[
 {
 "originalText": "Hello",
 "translatedText": "Bonjour"
 },
 {
 "originalText": "My dear",
 "translatedText": "Mon cher"
 },
 {
 "originalText": "Friend",
 "translatedText": "Ami"
 }
]

注意：您可以使用 json_decode 函数解码此字符串。

还没有明白？请查看下面的文档，困惑将会消除！

文档（含示例）

坦白说，这里不是每个人都能轻松开始使用这个包，所以让我们一起了解正在发生的事情。本节将涵盖 Mirza Yandex Translator 提供的每个方法的使用，以下是目录

1. translate 方法
2. translateArray 方法
   1. 使用顺序数组
   2. 使用关联数组
3. translateTo 方法
4. detectLanguage 方法
   1. 返回语言代码
   2. 返回语言名称
5. getSupportedLanguages 方法
6. translateToAll 方法
7. Blade 指令
   1. @translate 指令
   2. @yandex_rights 指令
   3. @languages_select 指令

示例

	$es_translation = Mirza::translate('Hello World!', 'es); //The first param is the text, the second one is the ISO code of the language
	echo $es_translation; //This will output "Hola Mundo!"

注意 所有 json 字符串都需要使用 PHP 的 json_decode 函数进行解码。 提示： 要返回 PHP 数组，请将 json_decode 的第二个参数设置为 true （例如 json_decode($jsonString, true);）。
如果你更喜欢操作 json 对象，请留空第二个参数或将其设置为 false。

Mirza::translateArray(['Hello', 'My Dear', 'Friend'], 'fr'); 此方法将给定的文本数组 ['Hello', 'My Dear', 'Friend'] 翻译成法语，如我们的示例所示。
此函数返回如下结构的 json 编码 字符串

[
 {
 "originalText": "Hello",
 "translatedText": "Bonjour"
 },
 {
 "originalText": "My dear",
 "translatedText": "Mon cher"
 },
 {
 "originalText": "Friend",
 "translatedText": "Ami"
 }
] 

如你所见，输出的 json 字符串 与输入数组保持相同的顺序，现在我们可以通过以下方式解码字符串来访问这些元素

	$jsonString = Mirza::translateArray(['Hello', 'My Dear', 'Friend'],'fr'); //The json string
	$translationsArray = json_decode($jsonString, true); //Our PHP Array
	$first_translation = $translationsArray[0]['translatedText'];
	$second_translation = $translationsArray[1]['translatedText'];
	$third_translation = $translationsArray[2]['translatedText'];

简单吧？但如果将 $assoc 参数设置为 true，则可以更容易地通过其索引名（你手动设置的）访问字符串翻译。在这里，没有人 会感到困惑，这里有一个例子

$textArray = [
	'header' => "Welcome to the Mirza Documentation Page",
	'body' => "The body is too long to be put in this item",
	'footer' => "Thank you for reading this!"
]; //Our associative text array
$jsonString = Marzi::translate($textArray,'es', true); //Notice that i have set $assoc (third param) to `true`
$translationsArray = json_decode($jsonString, true);
//Now you can access the translations by their old index names
	$header = $translationsArray['header']['translatedText'];
	$body = $translationsArray['body']['translatedText'];
	$footer = $translationsArray['footer']['translatedText'];

注意： 如果将 $assoc 设置为 true 并提供顺序数组，则将抛出异常。

此方法可能是先前函数的反向版本，它不是接收字符串数组，而是接收一个字符串并将其翻译成语言数组。 示例：

	$jsonString = Mirza::translateTo('My awesome text', ['ar', 'tr', 'de']);

上述示例将返回以下结构的 json 字符串

[
	{
		"originalText":"My awesome text",
		"originalLanguage": "en",
		"text":{
			"ar":"\u0628\u0644\u062f\u064a \u0627\u0644\u0646\u0635 \u0631\u0647\u064a\u0628\u0629",
			"tr":"M\u00fcthi\u015f metin",
			"de":"Meine wunderbare text"
		}

	}
]

你可能已经注意到，其中一些字符是以 Unicode 格式表示的，不用担心，如果你稍后使用 echo 显示，它将被正确显示。

现在我们可以轻松地解码此 json 字符串 并像这样访问我们的数据

	$translations = json_decode($jsonString, true); //Our PHP array
	$originalText = $translations['originalText'];
	$originalLanguage = $translations['originalLanguage'];
	$ar_translation = $translations['text']['ar'];
	$tk_translation = $translations['text']['tr'];
	$de_translation = $translations['text']['de'];

有时你需要检测一段文本使用的语言，为此，我们创建了 detectLanguage 方法！如方法表所述，此方法接受一个必需参数和一个可选参数。可选参数（布尔值 $name）允许我们切换返回语言 ISO 代码或语言名称。

示例

• 返回语言代码

//Leave the $name param empty or set it to `false`
//To return the language ISO code
$lang = Mirza::detectLanguage('Hello World!');
echo $lang; //Outputs "en"

• 返回语言名称

//Setthe $name param to `true`
//To return the language ISO code
$lang = Mirza::detectLanguage('Hello World!', true);
echo $lang; //Outputs "English"

此方法不接受任何参数（它应该接受，但将在以后的版本中添加）并且如果执行它，则返回所有支持的语言列表。

示例

//Save the json encoded string to the `$supportedLanguages` variable
$supportedLanguages = Mirza::getSupportedLanguages();
echo $supportedLanguages; 
/* Outputs the json string in the following format:
	[
		{ 'lang_code' => 'lang_name' },
		{ 'lang_code' => 'lang_name' },
	]
*/

我不想包含整个输出，因为它的长度太长，但如果你仍然好奇，我已经准备好了！这是一个截图：

让我们 解码 这个 json 字符串 并玩玩吧！

//Decode json string and wrap it into a PHP array
$langsArray = json_decode($supportedLanguages, true);

假设我们有一个语言代码，但我们不知道它指的是哪种语言，这行代码将在这方面帮我们很多

echo $langsArray['tr']; //Outputs "Turkish"

现在假设我们有一个语言名称，但我们不知道 ISO 代码，太简单了！ 我们可以使用 PHP 的 array_flip 函数来做这件事

$flippedArray = array_flip($langsArray); 
/* The values are now keys! Cool right? */
$languageCode = $flippedArray['Sinhalese'];
echo $languageCode; //Outputs "si"

示例

//Save the json string to a variable
$myStringInAllLanguages = Mirza::translateToAll('My string');
echo $myStringInAllLanguages; 
/*Outputs a similar string to the `translateTo` method but 
with all supported languages*/

• @translate：允许您即时将给定的文本翻译成指定的语言

  示例

   @translate('Welcome', 'fr') <!-- Outputs "Bienvenue" -->

• @yandex_rights：如果您已经阅读了Yandex.Translate 对使用翻译结果的要求，您就会知道这个指令会非常有用。
  您必须指定 color 作为第一个参数，以及 font-size 作为第二个参数。

  示例

   	@yandex_rights('black', '16px');
   	<!-- Output -->
   	<a href='https://translate.yandex.com/' target='_blank' style='font-size:16px;color:black;'>Powered by Yandex.Translate</a>

  • @languages_select：生成一个包含所有支持语言的 HTML <select> 列表。

  示例

    @languages_select
    <!-- Output -->
    <select>
   	<option value="lang_code">Lang_Name</option>
   	<option value="lang_code">Lang_Name</option>
   	<option value="lang_code">Lang_Name</option>
   </select>

方法

Mirza 中的所有内容都旨在简单易读，只需看一下 源代码，您就能立刻理解正在发生什么。但不用担心，我已经为您节省了麻烦，并制作了一个包含 Mirza 翻译器 提供的方法列表的表格。

Blade 指令

问题 & 建议

Mirza 只被一个人（显然是我 😃）测试过，这意味着如果您的 Mirza 安装出现问题或您认为还缺少某些功能，请通过提交新问题来告知我。

许可