PHPTAL

Этот атрибут объявляет одну или более переменных, которые затем могут быть использованы в шаблоне.

Объявление переменной, содержащей длинный путь:

<span tal:define="global destname path/to/existing/variable" />

Объявление строки внутри шаблона:

<span tal:define="global destname string:some string" />

Объявление нескольких переменных одновременно:

<span tal:define="global fname string:paul; lname string:dupond" />

Объявление переменной с использованием другой переменной:

<span tal:define="global hello string:hello $fname welcome on this page" />

И маленький трюк с использованием буфера вывода:

<span tal:define="global hello">hello ${fname} welcome on this page</span>

tal:define можно и удобно использовать вместе с другими атрибутами, но он всегда будет обработан первым.

В предпоследнем примере (объявление переменной с использованием другой переменной) тег span не будет отображен, т.к. он и сам пустой, и не содержит tal атрибутов, которые бы назначели его содержание. Даже в последнем примере текст из span не будет показан, т.к. переменная 'hello' его "съедает" (подменяет своим пустым значением)

Но вот другой пример:

<span tal:define="hello string:hello ${fname} welcome on this page"
      tal:content="hello"
/>

Здесь переменная 'hello' будет установлена, а ее содержимое попадет в тег span

однако, следующий пример неверный (точнее, не отобразит никакого содержания внутри span), т.к. tal:define определит содержание переменной 'hello' перед тем, как tal:content использует ее для определения того, что должно быть внутри элемента span. Чтобы не было указано внутри span в шаблоне, это будет проигнорированно (заменено значением переменной 'hello'). Но в нашем случае hello не будет определено, и поэтому возникнет исключение (exception).

<span tal:define="hello" tal:content="hello">
  hello ${fname} welcome on this page
</span>

Кстати, в этом примере мы не использовали слово 'global' перед определением переменной. В PHPTAL переменные бывают глобальными и локальными.

Глобальная переменная будет доступна во всем шаблоне и в вызываемых из него макросов.

<span tal:define="global hello string:hello world"/>
<p tal:content="hello"/>

Локальная же переменная видна только внутри тега, в котором она определена:

<span tal:define="hello string:hello world"/>
<p tal:content="hello"/> <!-- вызовет ошибку "неопределенной переменной" -->

Тег и его содержимое будет отображено только тогда, когда условие выполняется.

<span tal:condition="identified"> Приветствуем, наш любимый посетитель! </span>

<span tal:condition="not: identified">
  Пожалуйста, авторизуйтесь, чтобы получить доступ к этой странице
</span>

Если программисты PHP скрипта не предоставили Вам (разработчику шаблонов) нужные методы и переменные в передаваемых шаблону данных, Вы можете сами выполнить необходимый PHP код:

<span tal:comment="отобразить, только если в корзине больше 5-и позиций"
      tal:condition="php: cart.countItems() GT 5">…</span>

Частое использование инструкций <a0>PHP</a0> в шаблонах привело бы к тому, что логика скрипта была бы разбросана между PHP файлами и шаблонами, что уводит нас от изначальной идеи разделения кода и вида. Поэтому желательно обеспечить разработчиков шаблонов всеми нужными булевыми значениями и методами, например:

<span tal:condition="cart/hasMoreThanFiveItems">…</span>

<span tal:condition="fullfillNumerousItems">…</span>

Этот атрибут служит для циклов над перечисляемыми данными: массивами, ассоциативными массивами и перечисляемыми объектами в PHP5

Атрибут repeat поочередно пробегает по всем значениеям указанного ресурса (например, массива).

<tr tal:repeat="item some/result">
  <td tal:content="item">текст, который заменится значением из item</td>
</tr>

Внутри цикла можно использовать специальные ключевые слова repeat/*, чтобы получить доступ к информации об состоянии цикле (и всех внешних циклов).

Вот список допустимых ключевых слов:

в этих примерах, вместо названия "item" нужно использовать то же название, что и в выражении tal:repeat (tal:repeat="item some/result").

Одно из самых распространненных применений атрибута tal:repeat - отображение разультатов запроса к базе данных. Следующий пример сработает только в том случае, если playersRanking является объектом, реализующим интерфейс PHP Iterator:

<table>
  <thead>
    <tr>
      <th>Позиция</th>
      <th>Игрок</th>
      <th>Очки</th>
    </tr>
  </thead>
  <tbody>
    <tr tal:repeat="ranking playersRanking">
      <td tal:content="ranking/position"/>
      <td tal:content="ranking/player"/>
      <td tal:content="ranking/score"/>
    </tr>
  </tbody>
</table>

Этот атрибут заставит парсер PHPTAL проигнорировать открывающий и закрывающий теги элемента и вывести только его содержимое.

<span tal:omit-tag="condition">
  если условие condition верно, то только ЭТОТ текст будет показан (открывающий и закрывающий теги span будут упущены)
</span>

В результате получим:

если условие condition верно, то только ЭТОТ текст будет показан (открывающий и закрывающий теги span будут упущены)

Этот атрибут полезен, чтобы создать "опциональный" элемент. Например, спрятать ссылку, если какое-то условие не выполняется.

Если Вам нужен элемент, теги которого никогда не будут выведены, используйте tal:block

<tal:block tal:repeat="x php:range(1,10)">только этот текст будет выведен; 10 раз</tal:block>

Используя этот атрибут, можно заменить весь элемент целиком (включая открывающий и закрывающий тег) на заданную строку, или на пустую, если значение не задано.

<span tal:replace="string:я - прекрасная строка">
  а я строка плохая!
</span>

В результате получим:

я - прекрасная строка

tal:replace удобно использовать для создания примеров в шаблоне, которые должны быть игнорированы при его обработке перед отображением.

<table>
  <tr tal:repeat="item myresult">
    <td tal:content="item">значение item</td>
  </tr>
  <tr tal:replace="">
    <td>Пример 1</td>
  </tr>
  <tr tal:replace="">
    <td>Пример 2</td>
  </tr>
</table>

Значение этого атрибута станет текстом внутри тега.

<span tal:define="myvar string:моя строка"/>
<span tal:content="myvar">этот текст будет заменен</span>

В результате получим:

<span>моя строка</span>

С помощью tal:attributes можно устанавливать на лету значения атрибутов тега.

<a href="http://www.foo.com" title="some foo link"
   tal:attributes="href somelink/href; title somelink/title"
  tal:content="somelink/text"
>какая-нибудь ссылка</a>

Для примера, пусть значение 'somelink' будет таковым:

$somelink->href = "http://www.google.com";
$somelink->title = "google search engine";
$somelink->text = "the google search engine";

В результате получим:

<a href="http://www.google.com"
title="google search engine">the google search engine</a>

Точка с запятой (;) разделяет несколько атрибутов. Чтобы записать точку с запятой как часть значения, необходимо ее продублировать (;;).

Вот пример, где tal:attributes используется совместно с tal:repeat:

<tr tal:repeat="ranking playerRankings"
    tal:attributes="class php: repeat.ranking.odd ? 'odd' : NULL">
    …
</tr>

Модификатор php: будет описан ниже. Итак, рассмотрим наш пример. Если рядок нечетный, тогда для tr будет использован атрибут class="odd". Для четных же рядков атрибут class вообще не будет установлен.

"condition ? then : else" является специальным выражением PHP; хотя его польза имеет место быть во многих случаях, лучше попытаться избежать его использувания.

Правильнее было бы попросить PHP программиста обеспечить дизайнера шаблонов специальными модификаторами (см. PHP интеграция / пользовательские модификаторы), которые могли бы использоваться примерно так:

<tr tal:repeat="ranking playerRankings"
    tal:attributes="class css-odd:repeat/ranking/odd">
  …
</tr>

Модификатор возвратит "odd", если repeat/ranking/odd равен true, а иначе false.

… tal:attributes="title object/tooltip | nothing"> 

<input type="checkbox" tal:attributes="checked object/isChecked"/>

Значение этого атрибута подставится в тег, если тег содержит внутри себя ошибку (например, неверно заданный путь, или исключение, вызванное PHP во время генерации тега).

<span tal:on-error="string:Имя пользователя не определено"
      tal:content="user/name">этот текст заменится на имя пользователя</span>

Если доступ к 'name' или 'user' вызовет ошибку, то на месте тега будет показано сообщение об ошибке.

Этот механим работает для любой вложенности тегов:

<span tal:on-error="string:где-то возникла ошибка">
  <span tal:content="user/firstname"/>
  <span tal:content="user/lastname"/>
  <span metal:use-macro="userMenu" />
</span>

Этот атрибут объявляет макрос. По своей сути макросы это обычные шаблоны, которые могут быть многократно вставлены в другие шаблоны.

<div metal:define-macro="main_menu">
  <ul>
    <li><a href="/">Главная</a></li>
    <li><a href="/products">Продукция</a></li>
    <li><a href="/contact">Контакты</a></li>
  </ul>

  <div>
    Последнее обновление:
    <span tal:content="mdate">дата последнего обновления</span>
  </div>
</div>

Макрос наследует доступные переменные из вызывающего шаблона. В нашем примере значение переменной 'mdate' нужно объявить в шаблоне, в котором используют этот макрос.

Этот атрибут вызывает макрос и включает результат его выполнения в текущий шаблон в то место, откуда он вызван

<span
  tal:comment="шаблон main_menu требует переменную 'mdate'"
  tal:define="mdate page/last_modified"
  metal:use-macro="main_menu"
/>

Можно даже вызвать макрос из другого файла, просто дописав путь к нему:

<span metal:use-macro="site_macros.xhtml/main_menu"/>

При этом можно использовать всю гибкость подстановок переменных:

<span metal:use-macro="${design}/site_macros.xhtml/main_menu"/>

Макрос может вызывать самого себя. Таким образом, можно использовать рекурсию для вывода массивов:

        <ul metal:define-macro="show-list">
            <li tal:repeat="item list">
                <tal:block tal:condition="php:is_array(item)" tal:define="list item" metal:use-macro="show-list" />
                <tal:block tal:condition="php:!is_array(item)" tal:content="item" />
            </li>
        </ul>
        

Этот атрибут должен быть объявлен внутри тега, объявляющего макрос (metal:define-macro).

Слоты могут заменяться вызывающим шаблоном на динамически генерируемый XML/XHTML.

Cлоты помогают разнообразить страницы. Если макрос представить как целую страницу, то слоты можно предствить как секции, варьирующиеся в зависимости от, например, URL. К примеру, на той же главной странице сайта слот выводит свежие новости или перечень действий, доступных пользователю после его авторизации.

<span metal:define-slot="news_place">
  <table>
    <tr tal:repeat="item php:latestNews()">
      <td tal:content="item/value">news description</td>
    </tr>
  </table>
</span>

В этом примере мы определяем секцию под названием 'news_place', содержимое которой может быть подменено вызывающим шаблоном. Ниже мы рассмотрим, как использовать слоты, ссылаясь на этот пример.

Этот атрибут может быть использован только внутри элемента с metal:use-macro.

Он заставит PHPTAL подменить содержимое объявленного раньше слота.

<span tal:condition="logged" metal:fill-slot="news_place">
  <h2>Меню пользователя</h2>
  <ul>
    <li><a href="/user/action/inbox">входящие</a></li>
    <li><a href="/user/action/new">новые письма</a></li>
    <li><a href="/user/action/disconnect">выйти</a></li>
  </ul>
</span>

Таким образом, слоты позволяют с легкостью разнообразить и усложнить шаблоны с помощью простой технологии push.

Этот атрибут определяет текст, который должен быть переведен с помощью системы перевода, встроенной в PHPTAL.

<div i18n:translate="string:welcome_message">Добро пожаловать!</div>

В вышеприведенном примере PHPTAL будет искать перевод с ключем 'welcome_message' и заменит содержимое тега эквивалентным переводом.

<div i18n:translate="">Добро пожаловать!</div>

А это другой случай: ключ для перевода не указан, поэтому PHPTAL воспользуется содержимым 'Добро пожаловать!' как ключем для перевода. Таким образом, будет подставлен эквивалентный перевод для ключа 'Добро пожаловать!'.

Если же перевода с таким ключем не найдено, то в качестве перевода будет использован сам ключ. Именно поэтому лучше использовать читабельные сообщения в качестве ключей вместо непонятных сокращений.

Мало того, ключ может задаваться переменной:

<div tal:define="welcome random_welcome_message">
  <div i18n:translate="welcome">…</div>
</div>

Задает, какие атрибуты должны быть переведены. Пары значений Атрибут-Ключ должны быть перечислены через точку с запятой:

<img i18n:attributes="alt 'picture alternative text';title thetitle" alt="Picture" title="${thetitle}" />

В сам перевод можно динамически посдтавлять значения переменных. Для этого нужно назначить так называемые "переменные перевода", то есть, необходимо определить, какую переменную в переводе на какую реальную переменную (доступную в шаблоне) необходимо заменить. Для того, чтобы задать такое соответствие, используйте i18n:name

В строке перевода можно использовать запись ${xxx}, где "xxx" - название "переменной перевода", которая должна заменяться динамически на реальную переменную шаблона.

Соответствующее значение будет подставлено в тег и его содержимое. Если же Вы не хотите, чтобы значение было помещено в теги, используйте tal:replace вместо tal:content. Атрибут tal:omit-tag пригодится, если значение представляет собой конкатенацию строк.

<span i18n:name="myVar" tal:content="some/path"/>
<!-- <span>${some/path}</span> -->

<span i18n:name="myVar" tal:replace="some/path"/>
<!-- ${some/path} -->

<span i18n:name="myVar">foo</span>
<!-- <span>foo</span> -->

<span i18n:name="myVar" tal:omit-tag="">foo</span>
<!-- foo -->

Пример использования i18n:

<div i18n:translate="">
  Добро пожаловать, <span i18n:name="user" tal:replace="user/name"/>,
  у Вас <span i18n:name="mails" tal:replace="user/nbrMails"/>
  непрочитанных писем.
</div>

Ключ перевода в этом примере будет следующий:

"Добро пожаловать, ${user}, у Вас ${mails} непрочитанных писем."

В подставляемом переводе, PHPTAL заменит ${user} на ${user/name}, а ${mails} на ${user/nbrMails}.

Более подробно о связке I18N с PHPTAL можно прочитать в разделе PHP этой справки.

По умолчанию предполагается, что переводы содержат только текст и не содержат теги, поэтому PHPTAL экранирует все символы "<".

Начиная с версии 1.1.14, в i18n:translate допускается использования ключевого слова structure, чтобы отменить экранирование и выводить переведенный текст "как есть":

      <div i18n:translate="structure '<b>bold text</b>'" />
      

Даст:

        <div><b>bold text</b></div>
        

Однако, TAL атрибуты внутри переведенных строк будут игнорированы. Конечно, следует помнить, что плохо форматированный XHTML в переводах испортит хорошо форматированный шаблон.

Этот атрибут активирует отладку PHPTAL для тега с этим атрибутом.

The debug mode stores information like filename and source line number in the template, so exceptions thrown by incorrect path access will contain more information about where they where thrown.

<html>
  <head>
    …
  </head>
  <body>
    <div id="menu">
      …
    </div>
    <div id="leftPane" phptal:debug=""
      tal:comment="похоже, что этот div содержит ошибки,
      посмотрим-ка, где они возникают">
          …
    </div>
  </body>
</html>

Этот атрибут позволяет кешировать на диске результат обработки элемента (включая его тег). Готовое кешированное значение будет использовано до тех пор, пока срок действия кеша не истечет.

В атрибуте необходимо указать, как долго должен сохраниться кеш. Для этого нужно записать число с суффиксом 'd', 'h', 'm' или 's'.

<div class="footer" phptal:cache="3h">…</div>

<div> будет заново обработан как минимум раз в 3 часа.

Можно ограничить "видимость" кеша, дописав "per". По умолчанию, кеш видим всем страницам, использующим этот шаблон. Используйте "per url", чтобы заданный элемент кешировался отдельно для разных URL.

<ol id="breadcrumbs" phptal:cache="1d per url">…</ol>

<ol> будет кеширован на один день, отдельно для каждой страницы.

Можно указать "per expression", где expression - некое выражение. Тогда отдельные значения в кеше будут генерироваться для каждого разного значения этого выражения (выражение ДОЛЖНО в результате давать строку). Выражение не может использовать переменные, определенные в том же элементе с помощью tal:define.

<ul id="user-info" phptal:cache="25m per object/id">…</ul>

<ul> будет кешироваться каждые 25 минут, отдельно для каждого ID объекта.

<div phptal:cache="100d per php:news.id . news.last_modified_date">…</div>

Этот атрибут позволяет изменять "поведение" PHPTALES. По умолчанию, выражения атрибутов интерпретируются в максимальном соответствии с ZPT (Zope Page Templates). Однако, найдутся случаи, когда Вы бы хотели использовать PHP повсюду, то есть Вы бы везде применяли модификатор php:.

Другая проблема относительно PHPTALES состоит в способе, коим PHPTAL интерпретирует пути. Например, myobject/mymethod/property/10/othermethod/hashkey займет относительно много времени на интерпретацию (НО не концентрируйте на этом слишком много внимания; не нужно оптимизировать, пока вы не заметите реальное снижение производительности!)

PHPTAL должен (runtime) проверить, что myobject - это объект; проверить, что 'mymethod' - метод этого объекта (или, быть может, переменная), и затем вызвать его; убедиться, что результат является объектом со свойство; определить, что значение свойства - массив; найти десятый элемент этого массива и определить, что это объект; определить, что othermethod - метод этого объекта (а не переменная), и получить результат его вызова; определить, что результат - снова объект, и затем получить значение для ключа 'hashkey'.

Конечно, мы перегибаем палку в этом примере, и, на самом деле, чаще всего нас такие проблемы не будут волновать, та как этот процесс очень быстр. Но что, если этот очень длинный путь вызывается в большом цикле tal:repeat? Аминь!.. Именно тут phptal:tales приходит на помощь:

<html>
  <body>
    <table phptal:tales="php">
      <tr tal:repeat="myobject document.getChildren()">
        <td
          tal:content="myobject.mymethod().property[10].otherMethod().hashkey"></td>
      </tr>
    </table>
  </body>
</html>

Please note that the above example does the same as:

<html>
  <body>
    <table>
      <tr tal:repeat="myobject php:document.getChildren()">
        <td
          tal:content="php:myobject.mymethod().property[10].otherMethod().hashkey"></td>
      </tr>
    </table>
  </body>
</html>

О модификаторе 'php:' читайте подробнее в соответствующей главе .

This is the default modifier used in TAL expression when no other modifier is specified.

The following lines will give the same result:

<span tal:content="data/user/name"/>
<span tal:content="path:data/user/name"/>
<span>${data/user/name}</span>

Inside the template or inside expression strings, you can refer to a context variable using its path in the form ${path/to/my/variable}

<h1>${document/title}</h1>
<span tal:replace="string:welcome ${user/name},
this page has been readed ${page/countRead} times"/>

Because '<', '>' and '&' characters are cumbersome to use in XML, PHPTAL provides alternative syntax for PHP operators using these characters, and a few more for consistency.

These operators can be used only in php: expressions.

Because expressions are separated by a ';' character, and because '$' marks the start of a path, you must use:

<span tal:replace="string:this is a $$100 page"/>
string:foo $bar baz       <!-- will replace $bar -->
string:foo $$bar baz      <!-- no interpolation -->
string:foo ; php:doFoo()  <!-- two different expressions -->
string:foo ;; php:doFoo() <!-- only string -->

This expression evaluates what follows as a regular PHP expression except that '->' are replaced by dots '.' and variable names does not need to be prefixed with a dollar '$' sign.

A dot '.' separated from the rest of expression by spaces is assumed to be a concatenation sign.

php:htmlentities(foo)
php:'string ${varReplaced}'
php:'string ${some.path().to[0].var}'
php:NOT foo OR (bar GT baz)
php:a + b
php:array('a', 'b', 'c')
php:range(0, 90)
php:foo . a.b.c(e) . htmlentities(SomeClass::staticMethod())
php:SomeClass::ConstOfClass
php:SomeClass::$staticVar

php: should be used with care and won't be needed in 80% of your templates but sometimes you will need to invoke some special PHP method to be certain whether a user is logged in, or to retrieve specific complex data depending on some conditions, dynamically inside the template.

This expression is a boolean one, useful in tal:condition statements.

<span tal:condition="not: logged">not logged</span>

This expression returns true if the path specified after it exists, and false otherwise. It is analogous to PHP's isset().

Normally using a path which doesn't exist throws an error like "Cannot find variable 'foo' in current scope". Thus, uncertain paths must be checked first:

<span tal:condition="exists:user/preferences" tal:content="user/preferences">
  Use user/preferences here if defined
</span>

This is not an expression but a keyword, allowing template designers to keep the content of a tag as an alternative value if an error occurs, or if something is not defined.

<span tal:define="myVar path/to/possible/var | default">
  default my var value
</span>

<span tal:content="some/var | other/path | default">
  no some/var and no other/path found here
</span>

<a href="unknown.xhtml" title="Unknown page"
   tal:attributes="href item/href | default; title item/title | default"
   tal:content="item/title | default">Unknown page</a>

Above examples introduce the '|' character that allows the definition of alternatives for defines or prints.

This is not an expression modifier but a keyword.

While printing variables inside PHPTAL templates, you will have noticed that PHPTAL encodes each variable to ensure the validity of the output document.

Sometimes, you may use HTML/XML variables which must be echoed as is.

<h1 tal:content="structure document/title"/>
<span tal:replace="structure document/content"/>

In above examples, we assume that $document->title and $document->content are variables containing preformated HTML which must be echoed as is.

An expression chain is a list of expressions separated by '|' characters.

While evaluating expressions separated by '|', PHPTAL will stop its evaluation when an expression value is not null and no error was raised while evaluating the expression.

As a string: expression is always true, string: always terminates an expression chain whatever expression may follow.

You can use php: expressions inside expression chains, like any other expression.

<h1 tal:content="page/title | page/alternativeTitle | php:get_default_title()" />

This method may be called by the template to change the current output language.

Its arguments are a list of possible languages (use func_get_args() to get the argument array). The first known language should be used by your service.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
…
    public function setLanguage(){
        $langs = func_get_args();
        foreach($langs as $lang){
            // if $lang known use it and stop the loop
            $this->_currentLang = $lang;
            return;
        }
    }
    …
    private $_currentLang;
}
?>

If you decided to store your translations into separate files, one for each application, for example, this method allows you to select the translation domain from your templates (i18n:domain).

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    …
    public function useDomain($domain){
        if (!array_key_exists($domain, $this->_domains)){
            $file = "domains/$this->_currentLang/$domain.php";
            $this->_domains[$domain] = include($file);
        }
        $this->_currentDomain = $this->_domains[$domain];
    }
    …
    private $_currentDomain;
    private $_domains = array();
}
?>

The above example is a possible translation solution where keys are stored in PHP files which return an associative array of key => translation.

This method matches i18n:name calls. It builds an interpolation context for later translate calls.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    …
    public function setVar($key, $value){
        $this->_context[$key] = $value;
    }
    …
    private $_context = array();
}
?>

The last and most important method to implement, it asks your service to translate the specified key for the currently selected language.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    …
    public function translate($key){
        $value = $this->_currentDomain[$key];

        // interpolate ${myvar} using context associative array
        while (preg_match('/\${(.*?)\}/sm', $value, $m)){
            list($src,$var) = $m;
            if (!array_key_exists($var, $this->_context)){
                $err = sprintf('Interpolation error, var "%s" not set',
                               $var);
                throw new Exception($err);
            }
            $value = str_replace($src, $this->_context[$var], $value);
        }

        return $value;
    }
    …
}
?>

PHPTAL class calls this method to inform your translation service what encoding is used by the template. translate() method should return strings in that encoding. If you always use the same encoding for templates and translation files (i.e. UTF-8), you can leave this method empty.

The PHP gettext extension requires a specific structure which will contain your translation files.

/path/to/your/translation_root/en_US/LC_MESSAGES/
/path/to/your/translation_root/en_GB/LC_MESSAGES/
/path/to/your/translation_root/fr_FR/LC_MESSAGES/
/path/to/your/translation_root/es_ES/LC_MESSAGES/
… and so on …

The language code is composed of two characters defining the language itself (en, fr, es, …) and two characters defining the country (US, GB, FR, ES, …).

The directory pattern is:

<path_to_where_you_want>/<ll_CC>/LC_MESSAGES/

PO files are plain text files that contain your translation. You can safely edit them by hand.

po minimalistic example (en_US/LC_MESSAGES/mydomain.po):

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Simple test"
msgstr "A small sentence in english"

Once edited, each PO file must be indexed using:

msgfmt mydomain.po -o mydomain.mo

This command won't work if you don't have gettext tools installed on your system.

This will produce a MO file (machine object) indexing your translation for quick access.

Then you have to translate this file in other languages.

po minimalistic example (fr_FR/LC_MESSAGES/mydomain.po):

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Simple test"
msgstr "Une petite phrase en français"

The translation file must also be indexed:

msgfmt mydomain.po -o mydomain.mo

The domain is matched against your translation file names. In above examples we used 'mydomain' as domain name.

You can have more than one domain for the same application, it can enhance gettext's performance to split your application translations in more than one file.

<?php
require_once 'PHPTAL.php';
require_once 'PHPTAL/GetTextTranslator.php';

try {
    $tr = new PHPTAL_GetTextTranslator();

    // set language to use for this session (first valid language will
    // be used)
    $tr->setLanguage('en_GB.utf8', 'en_GB');

    // register gettext domain to use
    $tr->addDomain('mydomain', '/path/to/your/translation_root');

    // specify current domain
    $tr->useDomain('mydomain');

    $tpl = new PHPTAL('mytemplate.xhtml');

    // tell PHPTAL to use our translator
    $tpl->setTranslator($tr);

    // output translated template
    echo $tpl->execute();
}
catch (Exception $e){
    echo $e;
}

If you need to translate some other text, that is not in the template (e.g. plaintext e-mail message), you can reuse PHPTAL's translator:

$tr = $tpl->getTranslator();

$subject = $tr->translate("Registration information");

$tr->setVar("user",$username);
$message = $tr->translate("Dear ${user}, thanks for registering!");

mail($email, $subject, $message);

If you're using PHPTAL's standard gettext translator, you can use gettext() too.

The I18N namespace allows some variable interpolation in your translations.

# english
msgid "welcome"
msgstr "Welcome ${name} you have ${n} mails!"

# french
msgid "welcome"
msgstr "Bienvenue ${name} vous avez recu ${n} messages!"

A template can use this interpolation as follows:

<span i18n:translate="welcome">
  Welcome
  <span i18n:name="name" tal:replace="user/name"/>
  you currently have
  <span i18n:name="n" tal:replace="user/unreadeMails"/>
  unread messages!
</span>

Because i18n:translate contains a value 'welcome', the template data will be ignored and the message given by gettext will be used instead.