Translate Toolkit Documentation Release 1.12.0 Translate.org.za September 17, 2014 Contents 1 User’s Guide 3 1.1 Features..................................................3 1.2 Installation................................................4 1.3 Converters................................................5 1.4 Tools................................................... 51 1.5 Scripts.................................................. 85 1.6 Use Cases................................................. 97 1.7 Translation Related File Formats..................................... 113 2 Developer’s Guide 141 2.1 Translate Styleguide........................................... 141 2.2 Documentation.............................................. 147 2.3 Building................................................. 151 2.4 Testing.................................................. 151 2.5 Command Line Functional Testing................................... 153 2.6 Contributing............................................... 155 2.7 Translate Toolkit Developers Guide................................... 157 2.8 Making a Translate Toolkit Release................................... 161 2.9 Deprecation of Features......................................... 167 3 Additional Notes 169 3.1 Changelog................................................ 169 3.2 Release Notes.............................................. 177 3.3 History of the Translate Toolkit..................................... 192 3.4 License.................................................. 194 4 API Reference 195 4.1 API.................................................... 195 Python Module Index 467 i ii Translate Toolkit Documentation, Release 1.12.0 Welcome to Translate Toolkit’s documentation. This documenation covers both user’s and programmer’s perspective. Contents 1 Translate Toolkit Documentation, Release 1.12.0 2 Contents CHAPTER 1 User’s Guide This part has the user’s documentation for the tools included in the Translate Toolkit. 1.1 Features • Work with ONE localisation format. You’ll no longer be editing DTD files in one tool, .properties in another, OpenOffice GSI in a third. Simply do all your localisation in a PO or XLIFF editor • Converters for a number of formats – OpenOffice.org SDF/GSI – Mozilla: .properties, DTD, XHTML, .inc, .ini, etc – Others: Comma Separated Value, TMX, XLIFF, TBX, PHP, WordFast TXT, Qt .ts, txt, .ini, Windows .rc, ical, subtitles, Mac OS X strings • File access to localization files through the format API in all the above formats, as well as .qph, .qm, .mo • Output valid target file types. We make sure that your output files (e.g. .properties) contain all comments from the original file and preserves the layout of the original as far as possible. If your PO entry is marked as fuzzy we use the English text, not your half complete translation. The converters for OpenOffice.org and Mozilla formats will also perform simple checks and corrections to make sure you have none of those hard to find localisation bugs. • Our checker has over 42 checks to find errors such as: missing or translated variables, missing accelerator keys, bad escaping, start capitalisation, missing sentences, bad XML and much more. • Language awareness, taking language conventions for capitalisation, quotes and other punctuation into account • Find conflicting translations easily, cases where you have translated a source word differently or used a target word for 2 very different English concepts • Extract messages using simple text or a regular expression allowing you to quickly find and extract words that you need to fix due to glossary changes. • Merge snippets of PO files into your existing translations. • Create word, string and file counts of your files. Making it much easier to budget time as string counts do not give you a good indication of expected work. • Create a set of PO files with debugging entries to allow you to easily locate the source of translations. Very use- ful in OpenOffice.org which provides scant clues as to where the running application has sourced the message. The Translate Toolkit is also a powerful API for writing translation and localisation tools, already used by our own and several other projects. See the base class section for more information. 3 Translate Toolkit Documentation, Release 1.12.0 1.2 Installation This is a guide to installing the Translate Toolkit on your system. If the Translate Toolkit is already packaged for your system, this is probably the easiest way to install it. For Windows users, we provide installers. For several Linux distributions, the package might be available through your package manager. These packages might not be the absolute newest, or you might want to install from our packaged releases for some other reason. If your system already has the toolkit prepackaged, then please let us know what steps are required to install it. 1.2.1 Prerequisites • Remove old versions of toolkit on Debian The dollowing advice only applies to manual installation from tar ball. 1. Find location of your python packages: python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()" 2. Delete toolkit package from your Python site-packages directory e.g.: rm /usr/local/lib/python2.5/dist-packages/translate -R 1.2.2 Building For build instructions, see the Building page. 1.2.3 Download Download a stable released version. Or if you have a python environment, run easy_install translate-toolkit. For those who need problems fixed, or who want to work on the bleeding edge, get the latest source from Git. For most Windows users, the file named “translate-toolkit-...-setup.exe” is the best choice and contains everything you need if you just want to run Toolkit commands. If you want to use it for development, you will need to install it with easy_install or from the source package. If you install the complete “setup” version in Windows, or if you install through your distribution’s package manager, you should automatically have all the dependencies you need. If you are installing from the Version Control System, or from a source release, you should check the README file for information on the dependencies that are needed. Some of the dependencies are optional. The README file documents this. 1.2.4 Installing packaged versions Get the package for your system: -setup.exe A complete Windows installer containing all dependencies, including Python .exe An installer for a Windows with Python and other dependencies already installed RPM If you want to install easily on an RPM based system .tar.gz for source based installing on Linux .deb for Debian GNU/Linux (etch version) The RPM package can be installed by using the following command: 4 Chapter 1. User’s Guide Translate Toolkit Documentation, Release 1.12.0 rpm -Uvh translate-toolkit-1.0.1.rpm To install a tar.bz2: tar xvjf translate-toolkit-1.1.0.tar.bz2 cd translate-toolkit-1.1.0 su ./setup.py install On Windows simply click on the .exe file and follow the instructions. On Debian (if you are on etch), just type the following command: aptitude install translate-toolkit If you are using an old Debian stable system, you might want to install the .tar.bz2 version. Be sure to install python and python development first with: apt-get install python python-dev Alternatively newer packages might be in testing. 1.2.5 Installing from Git If you want to try the bleeding edge, or just want to have the latest fixes from a stabilising branch then you need to use Git to get your sources.: git clone https://github.com/translate/translate.git This will retrieve the master branch of the Toolkit. Further Git instructions are also available. Once you have the sources you have two options, a full install: su ./setup.py install or, running the tools from the source directory ./setuppath # Only needed the first time . setpath # Do this once for a session 1.2.6 Verify installed version To verify which version of the toolkit you have installed run: [l10n@server]# moz2po --version moz2po 1.1.0 1.3 Converters 1.3.1 General Usage The tools follow a general usage convention which is helpful to understand. 1.3. Converters 5 Translate Toolkit Documentation, Release 1.12.0 Input & Output The last two arguments of your command are the input and output files/directories: moz2po <input> <output> You can of course still us the -i and -o options which allows you to reorder commands moz2po -o <output> -i <input> Error Reporting All tools accept the option --errorlevel. If you find a bug, add this option and send the traceback to the develop- ers. moz2po<other-options>--errorlevel=traceback Templates If you are working with any file format and you wish to preserve comments and layout then use your source file as a template. po2dtd -t <source-file> <input> <output> This will use the files in <source-file> as a template, merge the PO files in <input>, and create new DTD files in <output> If you ran this without the templates you would get valid DTD files but they would not preserve the layout or all the comments from the source DTD file The same concept of templates is also used when you merge files. pomerge -t <old> <fixes> <new> This would take the <old> files merge in the <fixes> and output new PO files, preserving formatting, into <new>. You can use the same directory for <old> and <new> if you want the merges to overwrite files in <old>. source2target The converters all follow this convention: • source = the format from which you are converting e.g. in oo2po we are converting from OpenOffice.org SDF/GSI • target = the format into which you are converting e.g.