glen / smarty-gettext
Gettext plugin enabling internationalization in Smarty Package files
Requires
- php: ~5.3|~7.0
- ext-gettext: *
- ext-pcre: *
Requires (Dev)
- azatoth/php-pgettext: ~1.0
- smarty/smarty: 3.1.*
Suggests
- azatoth/php-pgettext: Support msgctxt for {t} via context parameter
This package is auto-updated.
Last update: 2022-02-01 12:28:02 UTC
README
smarty-gettext provides gettext (i18n) support for Smarty, the popular PHP templating engine, to implement an NLS (Native Language Support) API which can be used to internationalize and translate your PHP applications.
This README assumes that you already know what is gettext and how to use it with PHP.
If you don't, please visit the following websites before trying to use this package:
If you encounter problems when using the native gettext extension, you may want to try the php-gettext module, which emulates the behavior of the C extension, but is written in pure PHP.
This package has two parts:
block.t.php
,function.locale.php
- The Smarty plugins.tsmarty2c.php
- A command line utility that rips gettext strings from smarty source files and converts them to.pot
(PO-Template).
Installation
With Composer:
- Add the
"smarty-gettext/smarty-gettext": "~1.2.0"
into therequire
section of yourcomposer.json
:
composer require smarty-gettext/smarty-gettext=~1.2.0
- Run
composer install
.
Manually:
- Simply copy
block.t.php
andfunction.locale.php
to your Smarty plugins directory.
function.locale.php
Lets you set the locales path in master smarty template.
In order to use it put {locale path="PATH_TO_TRANSLATIONS_RELATIVE_TO_TEMPLATES_DIRECTORY" domain="YOUR_TRANSLATIONS_DOMAIN"}
somewhere in the top of your master template.
block.t.php
The Smarty plugin
Usage
The content of the block function is the string that you want to translate.
For example, for translating Hello World
, use: {t}Hello World{/t}
.
If you have dynamic parameters that should be set inside the string,
pass them to the block function, and they will be replaced with %n
,
where n
is 1
for the 1st parameter and so on.
For example, {t name="sagi"}my name is %1{/t}
will replace %1
with sagi.
The parameter name is ignored, unless it is one of the reserved names (see below). Only the parameters order matters.
Example for using multiple parameters:
{t 1='one' 2='two' 3='three'}The 1st parameter is %1, the 2nd is %2 and the 3rd %3.{/t}
NOTE: I decided to use numeric arguments instead of sprintf(), mainly because its syntax is simpler for the translators (especially when wanting to change the parameter order).
You can also use this method in your PHP code, by using the
smarty_gettext_strarg()
function. It is only loaded after block.t.php
is
included, so you probably want to copy it elsewhere.
I usually name the global version of this function strarg()
, and use it like this:
echo strarg(_('hi %1'), $name [,..]);
By default, all the translated strings will be automatically HTML escaped.
You may control this by setting the escape
parameter. Possible values:
html
for HTML escaping, this is the default.js
for javascript escaping.url
for url escaping.no
/off
/0
- disables escaping.
Example:
{t escape=no url="http://www.php.net/" name="PHP website"}
<a href="%1">%2</a>
{/t}
Using variables
Sometimes you need translated block passed as variable. This can be achieved with capture
block:
{capture assign="extra_title"}{t}Weekly report{/t}{/capture}
{include file="header.tpl.html" extra_title=$extra_title}
Plural support
The package also provides support for plural forms (see ngettext).
To provide a plural form:
- Set a parameter named
plural
with the plural version of the string. - Set a parameter named
count
with the variable count.
Plural and count are special parameters, and therefore, are not available as numeric arguments. If you wish to use the count value inside the string, you will have to set it again, as a numeric argument.
Example:
{t count=$files|@count 1=$files|@count plural="%1 files"}One file{/t}
Modifier support
A Smarty modifier support is not provided by this package.
I believe variables should be translated in the application level and provided after translation to the template.
If you need it anyway, it is easy to create such modifier, by simply registering the PHP gettext command as one.
tsmarty2c.php - the command line utility
This utility will scan templates for {t}...{/t}
placeholders for translation strings
and output a .pot
file (.po
template).
Usage:
./tsmarty2c.php -o template.pot <filename or directory> <file2> <...>
If a parameter is a directory, the template files within will be parsed, recursively.
In output special PO tags are added that inform about location of extracted translation. Most of the PO edit tools can respect that information.
If you wish to scan also .php
or .phtml
files for native gettext calls, you may wish to combine result of tsmarty2c
and xgettext
calls:
tsmarty2c -o smarty.pot ...
xgettext --add-comments=TRANSLATORS: --keyword=gettext --keyword=_ --output=code.pot ...
msgcat -o template.pot code.pot smarty.pot
rm -f code.pot smarty.pot
By default tsmarty2c
scans for .tpl
files, if you wish to use other files, you can use xargs
in unix:
find templates -name '*.tpl.html' -o -name '*.tpl.text' -o -name '*.tpl.js' -o -name '*.tpl.xml' | xargs tsmarty2c.php -o smarty.pot
See how it's done in Eventum project.
Authors
- Original Author: Sagi Bashari sagi@boom.org.il, http://smarty-gettext.sourceforge.net/
- Current maintainer: Elan Ruusamäe glen@delfi.ee
Copyright
Copyright (c) 2004-2005 Sagi Bashari
Copyright (c) 2010-2015 Elan Ruusamäe
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA