Community » Applications » Horde
Horde Translation Guide
Author: | Jan Schneider <jan@horde.org> |
---|---|
Author: | Chuck Hagenbuch <chuck@horde.org> |
Author: | Joris Braakman <jbraakman@yahoo.com> |
Contact: | horde@lists.horde.org (for administrators) |
Contact: | i18n@lists.horde.org (for translators) |
Contents
1 Administrator Guide
For translator documentation see the Translator Guide below.
1.1 GNU gettext, PHP and Horde
Horde uses GNU gettext for internationalization (i18n) and localization (l10n). The manual at http://www.gnu.org/software/gettext/manual/gettext.html is biased against C and using Emacs. This is more for Horde.
There is a good explanation for PHP and gettext at: http://www.faqts.com/knowledge-base/view.phtml/aid/2953/fid/422
People seem to like learning from examples better, so I have used dutch (nl_NL) as an example everywhere.
There is a command line tool written in PHP for creating and managing translations in the /usr/bin/ or horde/bin/ directory. Usage instructions can be found in the Translator Guide below as well as instructions on how to start and maintain translations.
1.2 Translations don't work
If all or some translations don't work on your system, please follow the steps described below. If you want to ask for help either on the i18n mailing list or on Horde's bug system, please explain which steps you tried and which failed.
You might also find some more information in the FAQ.
Please note that Dutch (nl_NL) is only used as an example here. If you have problems with a certain translation use this translation's language code instead. Most locales only use the language part of the locale name (the first two lowercase letters) for the actual translation directories, i.e. nl in this example. Prominent exceptions from this rule are Chinese (zh_TW, zh_CN) and Brazilian Portuguese (pt_BR).
Is this locale (nl_NL) installed at all?
locale -a should list all locales installed on your system.
On Debian and Ubuntu not all locales may be enabled by default. On Debian edit /etc/locale.gen and run locale-gen after you changed the list of enabled locales. On Ubuntu run locale-gen nl_NL for all locales that you want to install.
Do you have any .mo files?
Usually in /usr/share/locale/ e.g. /usr/share/locale/nl/LC_MESSAGES/tar.mo
Does gettext even work?
Get a string to translate:
$ strings /bin/tar | grep Memory Memory exhausted $ (LANG=nl_NL; LANGUAGE=nl_NL; LC_MESSAGES=nl_NL; gettext tar "Memory exhausted" ) Geheugen uitgeput
Does the local Horde file work?
Assuming that you have put the translated Horde file in /var/www/horde/locale/nl/LC_MESSAGES/horde.mo:
$ TEXTDOMAINDIR=/var/www/horde/locale LANG=nl_NL.utf8 LANGUAGE=nl_NL.utf8 LC_MESSAGES=nl_NL.utf8 gettext horde "Calendar" ) Agenda
Create a file in the horde directory, langtest.php:
<?php setlocale(LC_MESSAGES, 'nl_NL'); putenv('LANG=nl_NL'); putenv('LANGUAGE=nl_NL'); // use the tar test. echo dgettext('tar', 'Memory exhausted'); echo '<br />'; // Specify location of translation tables bindtextdomain('horde', './locale'); // Choose domain textdomain('horde'); // Print the already tested message echo _("Calendar"); echo '<br />'; // this should print the same. echo dgettext('horde', 'Calendar'); ?>
Output web browser:
Geheugen uitgeput Agenda Agenda
1.3 Solaris
Since the .mo files are binary, they are platform specific. You have to rerun make in all po directories.
On Solaris 7, you don't have the Partial Locales (SUNWploc) and Supplementary Partial Locales (SUNWploc1) packages installed if you get:
$ LANG=nl_NL couldn't set locale correctly
On Solaris 8, you must install the local packages required for the locales you desire (for example, you may need to install SUNWweuos for Western European locales or SUNWmeaos for Middle Eastern locales). The packages are located on Software Disk 1 of 2 in the directory: sol_8_1001_sparc/s0/Solaris_8/Product
This is what it should say:
Solaris 7:
$ pkginfo | grep ploc system SUNWploc Partial Locales system SUNWploc1 Supplementary Partial Locales
Solaris 8:
$ pkginfo | grep euo system SUNWceuos Central Europe OS Support system SUNWceuox Central Europe 64-bit OS Support system SUNWeeuos Eastern Europe OS Support system SUNWeeuox Eastern Europe 64-bit OS Support system SUNWneuos Northern Europe OS Support system SUNWneuox Northern Europe 64-bit OS Support system SUNWseuos Southern Europe OS Support system SUNWseuox Southern Europe 64-bit OS Support system SUNWweuos Western Europe OS Support system SUNWweuox Western Europe 64-bit OS Support
The stuff is installed in /usr/lib/locale:
$ ls /usr/lib/locale/nl LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME nl.so.1
It was reported that the HTTP server has to be linked to the same libintl.so file as PHP on Solaris. Also, it may be required that libintl.so be loaded before libc is loaded. If you are having conflicts, you may be able to reside them by starting apache with one of the following commands:
$ LD_PRELOAD=libintl.so apachectl start
1.4 FreeBSD
You also need UTF-8 support in FreeBSD. This is not installed by default in FreeBSD versions before 5.3, you need to install the utf8locale-without-swidth-040319 package or port in older versions.
2 Translator Guide
2.1 Translation Tool
horde-translation is a small PHP script that should help translators doing their work.
Any feedback, bug reports and feature requests should be send to the i18n mailing list. This is also the right place for new translations and general discussions of i18n and l10n questions and problems.
horde-translation is installed to your /usr/bin/ directory by default, if using PEAR to install Horde. Otherwise it's located in horde/bin/
For a list of available commands run:
horde-translation help
For detailed help on a certain command run:
horde-translation help command
Additional information about creating translations and fixing problems can be found in the Administrator Guide.
2.1.1 Prerequisites
To run this script you'll need a PHP command line executable with gettext support compiled in, and the basic PEAR libraries. The script expects your PHP executable to be in the binary search path. If your PHP executable cannot be found, either edit the first line of translation to reflect your location or call the script like:
/usr/local/bin/php translation.
You'll need the gettext package version 0.12 or greater.
You'll need the PEAR packages Console_Getopt 0.11 or greater, Console_Table and File_Find. To install all needed packages, run:
pear upgrade PEAR Console_Getopt pear install Console_Table File_Find
or download the newest package from the PEAR server and install them manually in your PEAR directory.
2.1.2 Creating a new translation
To create a new translation you first have to extract all gettext messages from the PHP sources. There are already template files with the .pot suffix in the locale directories that you can use if you have troubles extracting the messages, though these templates might be slightly outdated. Run:
horde-translation extract
You now have to create a new PO file for your language. A locale has the form ll_CC where ll is the two letter ISO 639 code of the language and CC the two letter ISO 3166 code of the country, e.g. de_DE, en_US or pt_BR. Only some languages require to specify the complete locale name, like Chinese (zh_CN or zh_TW). If you want to provide a country-specific language variant, e.g Brazilian Portuguese (pt_BR) or Canadian French (fr_CA) you need to use the full locale too. All other languages should only use the ll part of the locale as a parameter for the translation script.
horde-translation init -l ll
Now you can start the translation by editing the created locale/ll/LC_MESSAGES/[modulename].po files. You should fill out the the complete header of the created PO file, e.g.:
# Dutch translation for Horde. # Copyright 2004-2017 Horde LLC (http://www.horde.org/) # This file is distributed under the same license as the Horde package. # Joris Braakman <jbraakman@yahoo.com>, 2004. # msgid "" msgstr "" "Project-Id-Version: Horde 4.0\n" "Report-Msgid-Bugs-To: dev@lists.horde.org\n" "POT-Creation-Date: 2004-04-14 10:30+0200\n" "PO-Revision-Date: 2004-04-14 17:17+02:00\n" "Last-Translator: Joris Braakman <jbraakman@yahoo.com>\n" "Language-Team: i18n@lists.horde.org\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8-bit\n"
To compile the translations to a binary format run:
horde-translation make -l ll
After you created the new translation you have to add entries for this locale in the configuration file horde/config/nls.php.
If you create a new translation for a certain module but there are already translations for the same language for other modules, then you should use a compendium. This will save you a lot of time and it will make translations much more consistent.
2.1.3 Compendiums
This tool utilizes a nice feature of gettext: compendium files. A compendium is a special PO file containing a set of translations recurring in many different packages. These compendiums will be used in the background without much intervention required. But you have to create and edit a compendium before you can use it.
To create a compendium of all existing translations for a certain locale run:
horde-translation compendium -l ll
The compendium.po being created will contain all modules' translations of this locale merged into a single file. You should take a closer look at this file because you may find a lot of special marked lines where you translated certain strings differently in the various modules. It's a good idea to fix the modules' translations now so that all modules use the same translations for the same strings. You can always recreate your compendium with the above command.
If you're maintaining translations for different branches and assumed that you have all modules of the development branch in one directory and all of the stalbe branch in another, you probably want to share a compendium between these directories.
To do this, you should first create a compendium in the stable branch, review it and fix all translations until you're happy with the results. Then create a second compendium in the head branch and include your first one with the --add option. Now fix the translations in this branch. If you're ready you can remove the first compendium and for now on use the compendium in the development branch for both branches. To do so, use the -c or --compendium option to specify a path to your compendium.
If you translate directly from a git checkout, this is usually not necessary because you work with all branches in the same directory and simply switch between them with git checkout.
2.1.4 Updating translations
The process of updating translations is a cycle where you extract new gettext strings from the sources, translate those new strings or update the already translated strings and compile them after.
To update the translation for a module, run:
horde-translation update -m modulename -l ll
This extracts the new strings from the sources and tries to update them from already existing translations in the compendium. You just have to translate all untranslated strings in the modulename.po file in the locale/ll_CC/LC_MESSAGES directory of the module you updated.
If extracting new strings fails for some reason, you can use the provided .pot file instead to update your translation:
horde-translation merge -m modulename -l ll
If your compendium is in a different directory than the translation script, you can specify the path to the compendium:
horde-translation update -m modulename -l ll -c /path/to/compendium
Once this is done, you can compile the translation by calling:
horde-translation make -m modulename -l ll
2.1.5 Extending existent translations
To have your own string (e.g. that you added to config files) displayed in several languages, you have to
- specify your texts as gettext arguments, in English, e.g. by using the _() function or Horde_Translation methods.
- edit the translation files for the required national languages,
- compile those translation files.
Be sure to keep records of your extensions, as you will probably have to repeat steps 2 and 3 after the next update.
E.g., you plan to offer two IMAP servers to select from in the Webmail login screen:
In horde/imp/config/servers.php, you specify:
$servers['Central'] = array( 'name' => _("Central Mail Service"), ... $servers['CompSci'] = array( 'name' => _("Mail Service of Computer Science Dpt.") ...In horde/imp/locale/de/imp.po you add two entries:
msgid "Central Mail Service" msgstr "Zentraler Mailserver" msgid "Mail Service of Computer Science Dpt." msgstr "Mailserver Informatik"Likewise, you amend the translation files for other languages, as needed.
You compile the translations using the commands:
horde-translation make --module imp --no-compendium
2.1.6 "Raw" gettext strings
Horde provides a non-standard way to define a translatable string without having that string translated in the code. By using the Horde_Translation::r() method, the string will be marked as a translatable string and extracted by the Horde translation script, but the string will not be altered in the PHP code. Example:
// For a Horde package named Horde_Foo:: $str = Horde_Translation_Foo::r("Foo"); // -OR- For a Horde application:: $str = Horde_Translation_Core::r("Foo"); echo $str; // Output: Foo echo _($str); // Output: [Translation of 'Foo']
2.2 Access Keys
Access keys, also known as shortcut keys, allow easy access to important functions, normally by hitting the Alt/Meta key in combination with another key. This key is marked in most user interfaces by being underlined.
As the access key is part of the word representing the action being executed, it is in the translators responsibility to select an access key when he translates these words. The action is always a link in Horde. The access key of a link is selected by prefixing it with an underscore.
The help link in the menu for example is always "_Help". This means that the "H" of the link will be underlined and the help can be opened by hitting Alt+H. In the PO file this string will appear as:
#: templates/menu/menu.inc:53 msgid "_Help" msgstr ""
A Spanish translator might want to translate this to:
#: templates/menu/menu.inc:53 msgid "_Help" msgstr "_Ayuda"
Translators of multibyte languages need to do this a bit differently as only ASCII characters are allowed for access keys. A Traditional Chinese translator might want to use:
#: templates/menu/menu.inc:53 msgid "_Help" msgstr "_H說明"
This renders to "說明(H)" in the interface and you can access this link with "H" as the access key.
2.3 Right-to-Left Languages
Translations for languages that are written from right to left might cause unexpected behavior if parenthesis or similar characters appear inside a translated string. To fix this broken string rendering you have to insert special Unicode codepoints into the translated string.
Before such a string in parenthesis, add the U+202D codepoint. If there is more right-to-left text to come after the closing parenthesis, add the U+202E codepoint after it. If using the PO mode of the Emacs editor you can add codepoints with the "ucs-insert" command.
2.4 Help Texts
2.4.1 Organization of the help files
The help texts are available in the horde/locale/, and horde/APP/locale/, directories, where APP is any Horde application. Every available translation is kept in a file called help.xml, in a subdirectory named according to the language name. Examples:
- Horde's original help texts are in the horde/locale/en/help.xml file.
- IMP's Brazilian help texts are in the horde/imp/locale/pt_BR/help.xml file.
When, for any desired application and locale, there is no help.xml file available, Horde's help system will use the application's locale/en/help.xml file, instead.
The help files must be encoded in the UTF-8 character set.
There is no compilation step involved: Every modification to, or addition of, a help.xml file takes immediate effect.
2.4.2 Syntax of the help files
Each help file must consist of syntactically valid XML code.
There are no predefined entities beyond the XML standard entities:
- < (less than)
- > (greater than)
- & (ampersand)
- ' (ASCII apostrophe)
- " (ASCII quotation mark)
Any character available in the language's preferred character set can be entered as a numerical character reference (based on its Unicode scalar value), such as   for the No-Break Space character.
The general structure can be learned from the existing examples; of course, the XML tags must be syntactically valid, and properly nested.
Note
A PHP error message like Undefined index: url in /var/www/horde/lib/Horde/Help.php means that you have mis-spelled, or omitted, an attribute (url, in this example).
The following tags are available:
XML-Tag | Parent | Attributes | Purpose |
---|---|---|---|
help | — | — | List of help texts |
entry | help | id | Help text |
title | entry | — | Entry in the help index |
heading | entry | — | Level 2 heading |
para | entry | — | Paragraph |
ref | para | module, entry | Link into the help system |
eref | para | url | External link |
href | para | app, url | Link into a Horde application |
b | para | — | Bold text |
i | para | — | Italic text on new line |
pre | entry | — | Example box |
tip | entry | — | Tip/hint box |
warn | entry | — | Warning box |
The elements marked para, in the Parent column, may also be used within pre, tip, and warn elements.
The following attributes are available:
XML-Tag | Attribute | Purpose/Syntax |
---|---|---|
entry | id | Anchor |
ref | module | Index of Horde application, see horde/config/registry.php |
entry | Id of help file entry, see above | |
eref | url | arbitrary URL |
href | app | Index of Horde application, see horde/config/registry.php |
url | URL within Horde application |
Examples:
<ref module="imp" entry="compose-attachments">selecting attachments</ref> <eref url="http://wiki.horde.org/FAQ/User/IMP?referer=FAQ/User#toc17"> UW-IMAP quirk</eref> <href app="turba" url="search.php">Address search</href>
The Translation Tool will introduce additional attributes:
XML-Tag | Attribute | Purpose/Syntax |
---|---|---|
entry | state | See Finishing a translation |
md5 | Used internally |
2.4.3 Reference from the Horde applications
The typical incantation, e.g.:
<?php echo Horde_Help::link('imp', 'compose-buttons') ?>
will yield a link, adorned with the help.png icon, to the entry marked id="compose-buttons" in the IMP help file pertaining to the user's current locale. Usually, these links are placed in the template files, next to the item to be explained by the pertinent help entry.
The Horde menu will usually contain a general help item, which is generated in lib/Horde/Menu.php.
2.4.4 Creating a new translation
If necessary, define a suitable language name. E.g., if you plan to add an Austrian translation, you would use de_AT as your language name.
For Horde, and for all relevant applications, copy the help.xml files from the locale/en/ subdirectories to the locale/ll/ subdirectories, creating them if necessary.
Translate each new locale/ll/help.xml file, leaving all tags and attributes unchanged. Just translate the text between the tags.
Important
The id attributes must be kept unchanged, under any circumstances.
If the application is already translated and only the help files are missing, then be sure to use the same terminology as the existing translation. In any case, try to use a lucid, coherent terminology.
2.4.5 Finishing a translation
If you want to submit a translation to be included in the Horde code base, make sure that you have completed all translations. Then run:
horde-translation make-help -l ll
This will mark all entries as being up-to-date so that you or other translators can later see which entries have been changed since then.
2.4.6 Updating an existing translation
Run:
horde-translation update-help -l ll
This will merge your existing help file with all changes from the original, English help file since your last translation. Changed entries are marked with the attribute state="changed", new entries with state="new". The original entry from the English help file is added in a comment below a changed entry, so that you can easily compare them.
Translate the remaining English phrases, like discussed above. When your finished, remove any English entries and follow the steps at Finishing a translation.
2.4.7 Extending existent translations
If you feel that some feature should be better explained to the end user, then proceed as following:
- Determine, whether you will have to extend an existing entry, or add a new one.
- In the latter case, choose a suitable id for your new help entry.
- Edit the existing entry in, or add a new entry to, the application's en/help.xml file. Change all translations needed in your site in the same way. Be sure to use the same id everywhere.
- If you have added a new entry, you might want to add a link to it from a template, as explained above in Reference from the Horde applications.
- If you feel that your enhancement may be useful to other users, file an enhancement request at http://bugs.horde.org/ with a patch including your changes to the template and the help.xml files.
- In any case, keep notes of your changes, so you can apply them to later versions if necessary.