README 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  1. $Id: README,v 1.4 2005/07/27 18:14:59 sagi Exp $
  2. ------------------------------------------------
  3. | smarty-gettext - Gettext support for Smarty |
  4. | |
  5. | Author: Sagi Bashari <sagi@boom.org.il> |
  6. | URL: http://smarty-gettext.sourceforge.net/ |
  7. ------------------------------------------------
  8. smarty-gettext provides gettext support for Smarty,
  9. the popular PHP templating engine (http://smarty.php.net/).
  10. This README assumes that you already know what is gettext and how to
  11. use it with PHP.
  12. If you don't, please visit the following websites before trying to
  13. use this package:
  14. - http://www.php.net/gettext
  15. - http://www.onlamp.com/pub/a/php/2002/06/13/php.html
  16. If you encounter problems when using the native gettext extension,
  17. you may want to try the php-gettext module, which emulates the behavior
  18. of the C extension, but is written in pure PHP:
  19. http://savannah.nongnu.org/projects/php-gettext/
  20. This package has two parts:
  21. 1. block.t.php - The Smarty plugin.
  22. 2. tsmarty2c.php - A command line utility that rips gettext strings
  23. from smarty source files and converts them to C format.
  24. ---------------------------------
  25. | block.t.php - The Smarty plugin |
  26. ---------------------------------
  27. Installation
  28. ------------
  29. Simply copy block.t.php to your smarty plugins directory.
  30. Usage
  31. ------
  32. The content of the block function is the string that you want to translate.
  33. For example, for translating 'Hello World', use: {t}Hello World{/t}.
  34. If you have dynamic parameters that should be set inside the string,
  35. pass them to the block function, and they will be replaced with %n,
  36. where n is 1 for the 1st parameter and so on.
  37. For example, {t name="sagi"}my name is %1{/t} will replace %1 with sagi.
  38. The parameter name is ignored, unless it is one of the reserved
  39. names (see below). Only the parameters order matters.
  40. Example for using multiple parameters:
  41. {t 1='one' 2='two' 3='three'}The 1st parameter is %1, the 2nd is %2
  42. and the 3nd %3.{/t}
  43. NOTE: I decided to use numeric arguments instead of sprintf(),
  44. mainly because its syntax is simpler for the translators
  45. (especially when wanting to change the parameter order).
  46. You can also use this method in your PHP code, by using the
  47. smarty_gettext_strarg() function. It is only loaded after block.t.php is
  48. included, so you probably want to copy it elsewhere.
  49. I usually name the global version of this function strarg(), and use it like this:
  50. echo strarg(_('hi %1'), $name [,..]);
  51. By default, all the translated strings will be automatically HTML escaped.
  52. You may control this by setting the 'escape' parameter. Possible values:
  53. - 'html' for HTML escaping, this is the default.
  54. - 'js' for javascript escaping.
  55. - 'url' for url escaping.
  56. - 'no'/'off'/0 - disables escaping.
  57. Example:
  58. {t escape=no url="http://www.php.net/" name="PHP website"}
  59. <a href="%1">%2</a>
  60. {/t}
  61. Plural support
  62. --------------
  63. The package also provides support for plural forms (see ngettext).
  64. To provide a plural form:
  65. 1. Set a parameter named 'plural' with the plural version of the string.
  66. 2. Set a parameter named 'count' with the variable count.
  67. Plural and count are special parameters, and therefore, are not available
  68. as numeric arguments. If you wish to use the count value inside the string,
  69. you will have to set it again, as a numeric argument.
  70. Example:
  71. {t count=$files|@count 1=$files|@count plural="%1 files"}One file{/t}
  72. Modifier support
  73. ----------------
  74. A Smarty modifier support is not provided by this package.
  75. I believe variables should be trnalsated in the application level
  76. and provided after translation to the template.
  77. If you need it anyway, it is easy to create such modifier, by simply
  78. registering the PHP gettext command as one.
  79. ------------------------------------------
  80. | tsmarty2c.php - the command line utility |
  81. ------------------------------------------
  82. This utility will rip the translation strings from the smarty files,
  83. and convert them to gettext calls in C.
  84. The C output may later be used with the standard gettext tools (see xgettext).
  85. Usage:
  86. ./tsmarty2c.php <filename or directory> <file2> <..> > smarty.c
  87. If a parameter is a directory, the template files within will
  88. be parsed, recursively.
  89. TIP:
  90. The output also contains comments that point to the location of the file
  91. that the string has been ripped from.
  92. You can use the '--add-comments' parameter of xgettext to make it include
  93. these comments inside the PO file (suggested by Mike van Lammeren).
  94. NOTE:
  95. You may need to adjust the PHP bin path at the top of the file,
  96. or use 'php tsmarty2c.php' to run the script.
  97. -----------
  98. | Copyright |
  99. -----------
  100. Copyright (c) 2004-2005 Sagi Bashari
  101. This library is free software; you can redistribute it and/or
  102. modify it under the terms of the GNU Lesser General Public
  103. License as published by the Free Software Foundation; either
  104. version 2.1 of the License, or (at your option) any later version.
  105. This library is distributed in the hope that it will be useful,
  106. but WITHOUT ANY WARRANTY; without even the implied warranty of
  107. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  108. Lesser General Public License for more details.
  109. You should have received a copy of the GNU Lesser General Public
  110. License along with this library; if not, write to the Free Software
  111. Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA