國際化

國際化（I18N）是指在設計軟件時，使它可以無需做大的改變就能夠適應不同的語言和地區(qū)的需要。對于 Web 應用程序， 這有著特別重要的意義，因為潛在的用戶可能會在全球范圍內。 Yii 提供的國際化功能支持全方位信息翻譯，視圖翻譯，日期和數(shù)字格式化。

區(qū)域和語言

區(qū)域設置是一組參數(shù)以定義用戶希望能在他們的用戶界面所看到用戶的語言，國家和任何特殊的偏好。 它通常是由語言 ID 和區(qū)域 ID 組成。例如，ID “en-US” 代表英語和美國的語言環(huán)境。為了保持一致性， 在 Yii 應用程序中使用的所有區(qū)域 ID 應該規(guī)范化為?ll-CC，其中ll?是根據(jù)兩個或三個字母的小寫字母語言代碼?ISO-639?和?CC?是兩個字母的國別代碼?ISO-3166。 有關區(qū)域設置的更多細節(jié)可以看?ICU 項目文檔。

在 Yii中，我們經(jīng)常用 “l(fā)anguage” 來代表一個區(qū)域。

一個 Yii 應用使用兩種語言：yii\base\Application::$sourceLanguage 和 yii\base\Application::$language 。前者指的是寫在代碼中的語言，后者是向最終用戶顯示內容的語言。 而信息翻譯服務主要是將文本消息從原語言翻譯到目標語言。

可以用類似下面的應用程序配置來配置應用程序語言：

return [
    // 設置目標語言為俄語
    'language' => 'ru-RU',
    
    // 設置源語言為英語
    'sourceLanguage' => 'en-US',
    
    ......
];

默認的 yii\base\Application::$sourceLanguage 值是?en-US，即美國英語。 建議你保留此默認值不變，因為通常讓人將英語翻譯成其它語言要比將其它語言翻譯成其它語言容易得多。

你經(jīng)常需要根據(jù)不同的因素來動態(tài)地設置 yii\base\Application::$language ，如最終用戶的語言首選項。 要在應用程序配置中配置它，你可以使用下面的語句來更改目標語言：

// 改變目標語言為中文
\Yii::$app->language = 'zh-CN';

消息翻譯

消息翻譯服務用于將一條文本信息從一種語言（通常是 yii\base\Application::$sourceLanguage ） 翻譯成另一種語言（通常是 yii\base\Application::$language）。 它的翻譯原理是通過在語言文件中查找要翻譯的信息以及翻譯的結果。如果要翻譯的信息可以在語言文件中找到，會返回相應的翻譯結果； 否則會返回原始未翻譯的信息。

為了使用消息翻譯服務，需要做如下工作：

• 調用 Yii::t() 方法且在其中包含每一條要翻譯的消息；
• 配置一個或多個消息來源，能在其中找得到要翻譯的消息和翻譯結果；
• 讓譯者翻譯信息并將它們存儲在消息來源。

這個 Yii::t() 方法的用法如下，

echo \Yii::t('app', 'This is a string to translate!');

第一個參數(shù)指儲存消息來源的類別名稱，第二個參數(shù)指需要被翻譯的消息。

這個 Yii::t() 方法會調用?i18n?應用組件?來實現(xiàn)翻譯工作。這個組件可以在應用程序中按下面的代碼來配置，

'components' => [
    // ...
    'i18n' => [
        'translations' => [
            'app*' => [
                'class' => 'yii\i18n\PhpMessageSource',
                //'basePath' => '@app/messages',
                //'sourceLanguage' => 'en-US',
                'fileMap' => [
                    'app' => 'app.php',
                    'app/error' => 'error.php',
                ],
            ],
        ],
    ],
],

在上面的代碼中，配置了由 yii\i18n\PhpMessageSource 所支持的消息來源。模式?app*?表示所有以?app?開頭的消息類別名稱都使用這個翻譯的消息來源。該 yii\i18n\PhpMessageSource 類使用 PHP 文件來存儲消息翻譯。 每 PHP 文件對應單一類別的消息。默認情況下，文件名應該與類別名稱相同。但是，你可以配置 yii\i18n\PhpMessageSource::fileMap 來映射一個類別到不同名稱的 PHP 文件。在上面的例子中， 類別?app/error?被映射到PHP文件?@app/messages/ru-RU/error.php（假設?ru-RU?為目標語言）。如果沒有此配置， 該類別將被映射到?@app/messages/ru-RU/app/error.php?。

除了在PHP文件中存儲消息來源，也可以使用下面的消息來源在不同的存儲來存儲翻譯的消息：

• yii\i18n\GettextMessageSource 使用 GNU Gettext 的 MO 或 PO 文件保存翻譯的消息。
• yii\i18n\DbMessageSource 使用一個數(shù)據(jù)庫表來存儲翻譯的消息。

消息格式化

在要翻譯的消息里，你可以嵌入一些占位符，并讓它們通過動態(tài)的參數(shù)值來代替。你甚至可以根據(jù)目標語言格式的參數(shù)值來使用特殊的占位符。 在本節(jié)中，我們將介紹如何用不同的方式來格式化消息。

消息參數(shù)

在待翻譯的消息，可以嵌入一個或多個占位符，以便它們可以由給定的參數(shù)值取代。通過給不同的參數(shù)值，可以動態(tài)地改變翻譯內容的消息。 在下面的例子中，占位符?{username}?在?“Hello, {username}！”?中將分別被?'Alexander'和'Qiang'?所替換。

$username = 'Alexander';
// 輸出：“Hello, Alexander”echo \Yii::t('app', 'Hello, {username}!', [
    'username' => $username,
]);

$username = 'Qiang';
// 輸出：“Hello, Qiang”echo \Yii::t('app', 'Hello, {username}!', [
    'username' => $username,
]);

當翻譯的消息包含占位符時，應該讓占位符保留原樣。這是因為調用?Yii::t()?時，占位符將被實際參數(shù)值代替。

你可以使用?名稱占位符?或者?位置占位符，但不能兩者都用在同一個消息里。

前面的例子說明了如何使用名稱占位符。即每個占位符的格式為?{參數(shù)名稱}?，你所提供的參數(shù)作為關聯(lián)數(shù)組， 其中數(shù)組的鍵是參數(shù)名稱（沒有大括號），數(shù)組的值是對應的參數(shù)值。

位置占位符是使用基于零的整數(shù)序列，在調用?Yii::t()?時會參數(shù)值根據(jù)它們出現(xiàn)位置的順序分別進行替換。 在下面的例子中，位置占位符?{0}，{1}?和?{2}?將分別被?$price，$count?和?$subtotal?所替換。

$price = 100;
$count = 2;
$subtotal = 200;
echo \Yii::t('app', 'Price: {0}, Count: {1}, Subtotal: {2}', $price, $count, $subtotal);

提示：大多數(shù)情況下你應該使用名稱占位符。這是因為參數(shù)名稱可以讓翻譯者更好的理解要被翻譯的消息。

格式化參數(shù)

你可以在消息的占位符指定附加格式的規(guī)則，這樣的參數(shù)值可在替換占位符之前格式化它們。在下面的例子中， 價格參數(shù)值將視為一個數(shù)并格式化為貨幣值：

$price = 100;
echo \Yii::t('app', 'Price: {0, number, currency}', $price);

注意：參數(shù)的格式化需要安裝?intl PHP 擴展。

可以使用縮寫的形式或完整的形式來格式化占位符：

short form: {PlaceholderName, ParameterType}
full form: {PlaceholderName, ParameterType, ParameterStyle}

請參閱?ICU 文檔?關于如何指定這樣的占位符的說明。

接下來我們會展示一些常用的使用方法。

數(shù)字

參數(shù)值應該被格式化為一個數(shù)。例如，

$sum = 42;
echo \Yii::t('app', 'Balance: {0, number}', $sum);

你可以指定參數(shù)的格式為?integer（整型），currency?（貨幣），或者?percent?（百分數(shù)）：

$sum = 42;
echo \Yii::t('app', 'Balance: {0, number, currency}', $sum);

你也可以指定一個自定義模式來格式化數(shù)字。 例如，

$sum = 42;
echo \Yii::t('app', 'Balance: {0, number, ,000,000000}', $sum);

格式化參考。

日期

該參數(shù)值應該被格式化為一個日期。 例如，

echo \Yii::t('app', 'Today is {0, date}', time());

你可以指定一個可選的參數(shù)格式?short?，medium?，long?，或?full?：

echo \Yii::t('app', 'Today is {0, date, short}', time());

你還可以指定一個自定義模式來格式化日期：

echo \Yii::t('app', 'Today is {0, date, yyyy-MM-dd}', time());

格式化參考。

時間

參數(shù)值應該被格式化為一個時間。 例如，

echo \Yii::t('app', 'It is {0, time}', time());

你可以指定一個可選的參數(shù)格式?short?，medium?，long?，或?full?：

echo \Yii::t('app', 'It is {0, time, short}', time());

你還可以指定一個自定義模式來格式化時間：

echo \Yii::t('app', 'It is {0, date, HH:mm}', time());

格式化參考。

拼寫

參數(shù)值為一個數(shù)并被格式化為它的字母拼寫形式。 例如，

// 輸出："42 is spelled as forty-two"echo \Yii::t('app', '{n,number} is spelled as {n, spellout}', ['n' => 42]);

序數(shù)詞

參數(shù)值為一個數(shù)并被格式化為一個序數(shù)詞。 例如，

// 輸出："You are the 42nd visitor here!"echo \Yii::t('app', 'You are the {n, ordinal} visitor here!', ['n' => 42]);

持續(xù)時間

參數(shù)值為秒數(shù)并被格式化為持續(xù)的時間段。 例如，

// 輸出："You are here for 47 sec. already!"echo \Yii::t('app', 'You are here for {n, duration} already!', ['n' => 47]);

復數(shù)

不同的語言有不同的方式來表示復數(shù)。 Yii 提供一個便捷的途徑，即使是非常復雜的規(guī)則也使翻譯消息時不同的復數(shù)形式行之有效。 取之以直接處理詞形變化規(guī)則，它是足以面對某些詞形變化語言的翻譯。 例如，

// 當 $n = 0 時，輸出："There are no cats!"// 當 $n = 1 時，輸出："There is one cat!"// 當 $n = 42 時，輸出："There are 42 cats!"echo \Yii::t('app', 'There {n, plural, =0{are no cats} =1{is one cat} other{are # cats}}!', ['n' => $n]);

在上面的多個規(guī)則的參數(shù)中，?=0?意味著?n?的值是 0 ，=1?意味著?n?的值是 1 ， 而?other?則是對于其它值，?#?會被?n?中的值給替代。

復數(shù)形式可以是某些非常復雜的語言。下面以俄羅斯為例，=1?完全匹配?n = 1，而?one?匹配?21?或?101：

Здесь {n, plural, =0{котов нет} =1{есть один кот} one{# кот} few{# кота} many{# котов} other{# кота}}!

注意，上述信息主要是作為一個翻譯的信息，而不是一個原始消息，除非設置應用程序的 yii\base\Application::$sourceLanguage 為?ru-RU。

如果沒有找到一個翻譯的原始消息，復數(shù)規(guī)則 yii\base\Application::$sourceLanguage 將被應用到原始消息。

要了解詞形變化形式，你應該指定一個特定的語言，請參考?rules reference at unicode.org。

選擇

可以使用?select?參數(shù)類型來選擇基于參數(shù)值的短語。例如，

// 輸出："Snoopy is a dog and it loves Yii!"echo \Yii::t('app', '{name} is a {gender} and {gender, select, female{she} male{he} other{it}} loves Yii!', [
    'name' => 'Snoopy',
    'gender' => 'dog',
]);

在上面的表達中，?female?和?male?是可能的參數(shù)值，而?other?用于處理不與它們中任何一個相匹配的值。對于每一個可能的參數(shù)值， 應指定一個短語并把它放在在一對大括號中。

指定默認翻譯

你可以指定使用默認的翻譯，該翻譯將作為一個類別，用于不匹配任何其他翻譯的后備。這種翻譯應標有?*?。 為了做到這一點以下內容需要添加到應用程序的配置：

//配置 i18n 組件

'i18n' => [
    'translations' => [
        '*' => [
            'class' => 'yii\i18n\PhpMessageSource'
        ],
    ],
],

現(xiàn)在，你可以使用每一個還沒有配置的類別，這跟 Yii 1.1 的行為有點類似。該類別的消息將來自在默認翻譯?basePath?中的一個文件， 該文件在?@app/messages?：

echo Yii::t('not_specified_category', 'message from unspecified category');

該消息將來自?@app/messages/<LanguageCode>/not_specified_category.php?。

翻譯模塊消息

如果你想翻譯一個模塊的消息，并避免使用單一翻譯文件的所有信息，你可以按照下面的方式來翻譯：

<?php

namespace app\modules\users;

use Yii;

class Module extends \yii\base\Module{
    public $controllerNamespace = 'app\modules\users\controllers';

    public function init()
    {
        parent::init();
        $this->registerTranslations();
    }

    public function registerTranslations()
    {
        Yii::$app->i18n->translations['modules/users

?>
<h2>This message allows you to visit our site home page by one click</h2>
<?= Html::a('Go to home page', Url::home('http')) ?>

為了通過視圖文件撰寫正文可傳遞視圖名稱到?compose()?方法中：

Yii::$app->mailer->compose('home-link') // 渲染一個視圖作為郵件內容
    ->setFrom('from@domain.com')
    ->setTo('to@domain.com')
    ->setSubject('Message subject')
    ->send();

你也可以在?compose()?方法中傳遞一些視圖所需參數(shù)，這些參數(shù)可以在視圖文件中使用：

Yii::$app->mailer->compose('greetings', [
    'user' => Yii::$app->user->identity,
    'advertisement' => $adContent,
]);

你可以指定不同的視圖文件的 HTML 和純文本郵件內容：

Yii::$app->mailer->compose([
    'html' => 'contact-html',
    'text' => 'contact-text',
]);

如果指定視圖名稱為純字符串，它的渲染結果將被用來作為 HTML Body，同時純文本正文將被刪除所有 HTML 實體。

視圖渲染結果可以被包裹進布局，可使用 yii\mail\BaseMailer::htmlLayout 和 yii\mail\BaseMailer::textLayout 來設置。 它的運行方式跟常規(guī)應用程序的布局是一樣的。布局可用于設置郵件 CSS 樣式或其他共享內容：

<?phpuse yii\helpers\Html;

?><?php $this->beginPage() ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=<?= Yii::$app->charset ?>" />
    <style type="text/css">
        .heading {...}
        .list {...}
        .footer {...}
    </style>
    <?php $this->head() ?>
</head>
<body>
    <?php $this->beginBody() ?>
    <?= $content ?>
    <div class="footer">With kind regards, <?= Yii::$app->name ?> team</div>
    <?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>

文件附件

你可以使用?attach()?和?attachContent()?方法來添加附件的信息：

$message = Yii::$app->mailer->compose();

// 附件來自本地文件$message->attach('/path/to/source/file.pdf');

// 動態(tài)創(chuàng)建一個文件附件$message->attachContent('Attachment content', ['fileName' => 'attach.txt', 'contentType' => 'text/plain']);

嵌入圖片

你可以使用?embed()?方法將圖片插入到郵件內容。此方法返回會圖片 ID ，這將用在 "img" 標簽中。 當通過視圖文件來寫信時，這種方法易于使用：

Yii::$app->mailer->compose('embed-email', ['imageFileName' => '/path/to/image.jpg'])
    // ...
    ->send();

然后在該視圖文件中，你可以使用下面的代碼：

<img src="/docs/guide/2.0/<?= $message->embed($imageFileName); ?>">

測試和調試

開發(fā)人員常常要檢查一下，有什么電子郵件是由應用程序發(fā)送的，他們的內容是什么等。這可通過yii\mail\BaseMailer::useFileTransport?來檢查。 如果開啟這個選項，會把郵件信息保存在本地文件而不是發(fā)送它們。這些文件保存在yii\mail\BaseMailer::fileTransportPath?中，默認在 '@runtime/mail' 。

提示: 你可以保存這些信息到本地文件或者把它們發(fā)送出去，但不能同時兩者都做。

郵件信息文件可以在一個普通的文本編輯器中打開，這樣你就可以瀏覽實際的郵件標題，內容等。這種機制可以用來調試應用程序或運行單元測試。

提示: 該郵件信息文件是會被?\yii\mail\MessageInterface::toString()?轉成字符串保存的，它依賴于實際在應用程序中使用的郵件擴展。

創(chuàng)建自己的郵件解決方案