Copyright © 2005 J. Martin Longo
This document is related to Koha and is licensed to you under the GNU General Public License version 2 or later (http://www.gnu.org/licenses/gpl.html).
Koha-related documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies.
You may create a derivative work and distribute it provided that you:
License the derivative work with this same license, or the Linux Documentation Project License (http://www.tldp.org/COPYRIGHT.html). Include a copyright notice and at least a pointer to the license used.
Give due credit to previous authors and major contributors.
Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.
No liability for the contents of this document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility.
All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.
2005-06-22
| Revision History | |
|---|---|
| Revision 2.2.2 | 2005-06-22 |
Initial XML markup. | |
Note
It's assumed, in every example, that you have downloaded the file koha-2.x.tar.gz and that you have unpacked it in the 'home' directory of the 'user' user. Provided this, you should have a koha-2.x directory under /home/user/
In each system, directory and user names should be replaced accordingly.
KOHA internationalization can be achieved in several ways. Not so long ago, it was necesary to copy the entire /home/usuario/koha-2.x/intranet-html/intranet-tmpl/default/en directory into another (i.e. /home/usuario/koha-2.x/intranet-html/intranet-tmpl/default/es) then manually edit each one of the templates contained in the newly created directory, translating the text strings they contain, trying, of course, not to touch or change anything else. Once the translation was finished, it was only necesary to configure KOHA's 'opaclanguages' System Preference to use the new language (i.e. es).
This procedure works and has produced acceptable results but is, obviously, very slow and difficult.
Now, thanks to KOHA's developer team, we have the tmpl_process3.pl script (provided with the KOHA distribution).
In short, this script takes the file or directory that we want to translate (i.e. /home/usuario/koha-2.x/intranet-html/intranet-tmpl/default/en) and generates a single '.po' file (.po comes from Portable Object) containing only the text strings contained inside KOHA's template files. This type of file is a format standard in the software internationalization work in the Free Software world and, because of this, there are several tools developed to edit them.
The present tutorial aims to show how to use the tmpl_process3.pl script to generate a '.po' file from KOHA's templates, introduce the use of one of the tools developed for '.po' files treatment (Kbabel) and then the use of the tmpl_process3.pl script again, to generate a set of translated templates for use in our KOHA installation.
The tmpl_process3.pl script lives under the /home/usuario/koha-2.x/scripts/misc/translator/ directory and depends on some modules located under the same directory. Because of this, in order for it to work, the script must be run from inside that directory.
Example 1. Running tmpl_process3.pl
user@host: cd /home/usuario/koha-2.x/scripts/misc/translator/ user@host: ./tmpl_process3.pl --help
The previous command will produce, as output, a list of options and a little help about the script's usage, as shown below:
Usage: ./tmpl_process3.pl create [OPTION]
or: ./tmpl_process3.pl update [OPTION]
or: ./tmpl_process3.pl install [OPTION]
or: ./tmpl_process3.pl --help
Create or update PO files from templates, or install translated templates.
-i, --input=SOURCE Get or update strings from SOURCE file.
SOURCE is a directory if -r is also specified.
-o, --outputdir=DIRECTORY Install translation(s) to specified DIRECTORY
--pedantic-warnings Issue warnings even for detected problems
which are likely to be harmless
-r, --recursive SOURCE in the -i option is a directory
-s, --str-file=FILE Specify FILE as the translation (po) file
for input (install) or output (create, update)
-x, --exclude=REGEXP Exclude files matching the given REGEXP
--help Display this help and exit
The -o option is ignored for the "create" and "update" actions.
Try `perldoc ./tmpl_process3.pl' for perhaps more information.To create a 'circ_es.po' containing the text strings of the English templates located in the 'circ' directory of the KOHA's intranet, the procedure would be:
user@host: cd /home/user/koha-2.x/scripts/misc/translator/ user@host: ./tmpl_process3.pl create -r -i /home/user/koha-2.x/intranet-html/intranet-tmpl/default/en/circ/ -s /home/user/translation/circ_es.po
In the above example:
'create' indicates that we want to create a new '.po' file.
-r indicates that the source is a directory.
-i indicates the path from where the text string will be extracted.
-s indicates the path and name of the '.po' file that will be created.
When running the script, there may be some 'warnings' about syntax errors in the original templates.
Output will look like this:
Warning: Can't determine original templates' charset, defaulting to ISO-8859-1 Removing empty file /home/user/tmp/temp.po xgettext.pl: Warning (negligible): selectbranchprinter.tmpl: line 15: Suggest ESCAPE=HTML for TMPL_VAR in attribute "value": "<!-- TMPL_VAR NAME="value" -->" xgettext.pl: Warning (negligible): selectbranchprinter.tmpl: Further similar negligible warnings will not be reported, use --pedantic for details xgettext.pl: Warning: returns.tmpl: line 17: Strange attribute syntax: /cgi-bin/koha/moremember.pl?bornum=<!-- TMPL_VAR NAME="bornum" -->", "Member"); return false;" xgettext.pl: Warning: branchtransfers.tmpl: line 20: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;" xgettext.pl: Warning: branchtransfers.tmpl: line 22: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;" xgettext.pl: Warning: branchtransfers.tmpl: line 98: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;" xgettext.pl: Warning: branchtransfers.tmpl: line 128: Probably missing whitespace before or missing quotation mark near: Item", 480, 640); return false;" The create seems to be successful.
Despite these warnings, the last line (The create seems to be successful.) indicates that the process has ended successfully and that now we have our brand new 'circ_es.po' file in /home/user/translation/ so now we can use Kbabel to begin the translation process.
The KBabel application presents four areas, inside the mail window, each one oriented to a particular function. You'll work translating the text strings extracted from the templates one by one.
To achieve this efficiently, KBabel gives you several tools, as can be seen in the next screenshot:
The area marked as Original Text is read only and displays the text string to be translated.
The area marked as Translated Text is where we will write the translation of the string displayed in the Original Text area.
The area marked as File Names displays the path and name of the template files where the text string being translated was extracted from.
The area marked as Context displays the previous and next text strings to the one being translated, to provide some help about the context of the current text string.
Some tags and markups should not be modified during translation:
Whenever the translation implies the use of accented words or special characters, they should be replaced with the corresponding entities, to avoid visualisation problems or errors.
To navigate between text strings and launch some useful commands, there are shortcuts in the toolbar and many keyboard key combinations.
| Command | Keyboard |
| Next text string | PgDown |
| Previous text string | PgUp |
| Next not translated text string | Alt+PgDown |
| Previous not translated text string | Alt+PgUp |
| Copy the text string displayed on the Original Text area to the Translated Text area | Ctrl+Space |
Following the previous examples, we have created a '.po' file named circ_es.po containing all the text strings present in the templates located at /home/user/koha-2.x/intranet-html/intranet-tmpl/default/en/circ
Afterwards, we used Kbabel to translate all those text strings.
Finally, we only need to generate a new set of translated templates, using the original ones as a basis. For this example, we will create our new set of translated templates in the /home/user/koha-2.x/intranet-html/intranet-tmpl/default/es/circ directory.
To achieve this, we'll use the tmpl_process3.pl script again, but with slightly different parameters:
user@host: cd /home/user/koha-2.x/scripts/misc/translator/ user@host: ./tmpl_process3.pl install -s /home/user/translation/circ_es.po -r -i /home/user/koha-2.x/intranet-html/intranet-tmpl/default/en/circ/ -o /home/user/koha-2.x/intranet-html/intranet-tmpl/default/es/circ/
In the above example:
'install' indicates that we want to create a set of templates from a '.po' file.
-r indicates that the target is a directory.
-i indicates the path where the original templates are located (the ones we extracted the text strings from).
-s indicates the path and name of the '.po' file that will be used in the process.
-o indicates the path where the new set of translated templates will be created.
As happened when we launched the script to create the '.po' file, there may be some 'warnings' about syntax errors in the original templates.
Output will look like this:
Warning: Can't determine original templates' charset, defaulting to ISO-8859-1 Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//selectbranchprinter.tmpl... tmpl_process3.pl: Warning (negligible): selectbranchprinter.tmpl: line 15: Suggest ESCAPE=HTML for TMPL_VAR in attribute "value": "<!-- TMPL_VAR NAME="value" -->" tmpl_process3.pl: Warning (negligible): selectbranchprinter.tmpl: Further similar negligible warnings will not be reported, use --pedantic for details Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//returns.tmpl... tmpl_process3.pl: Warning: returns.tmpl: line 17: Strange attribute syntax: /cgi-bin/koha/moremember.pl?bornum=<!-- TMPL_VAR NAME="bornum" -->", "Member"); return false;" Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//circulation.tmpl... Creating /home/jmlongo/documentos/koha/koha-2.1.1/intranet-html/intranet-tmpl/default/pl/circ//branchtransfers.tmpl... tmpl_process3.pl: Warning: branchtransfers.tmpl: line 20: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;" tmpl_process3.pl: Warning: branchtransfers.tmpl: line 22: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;" tmpl_process3.pl: Warning: branchtransfers.tmpl: line 98: Probably missing whitespace before or missing quotation mark near: Member", 480, 640); return false;" tmpl_process3.pl: Warning: branchtransfers.tmpl: line 128: Probably missing whitespace before or missing quotation mark near: Item", 480, 640); return false;" The install seems to be successful.
Despite these warnings, the last line (The install seems to be successful.) indicates that the process has ended successfully and that now we have our brand new set of translated templates at /home/user/koha-2.x/intranet-html/intranet-tmpl/default/es/circ directory.
To verify this you can use your favorite text editor to open one of the various templates located in that directory.
If you have any questions about the process outlined in this document or a comment that helps to improve it, you can reach me (Martin Longo) at <jmlongo AT uncu.edu.ar>.