Translate Toolkit Documentation Release 2.0.0
Total Page:16
File Type:pdf, Size:1020Kb
Translate Toolkit Documentation Release 2.0.0 Translate.org.za January 27, 2017 Contents 1 User’s Guide 3 1.1 Features..................................................3 1.2 Installation................................................4 1.3 Converters................................................6 1.4 Tools................................................... 56 1.5 Scripts.................................................. 91 1.6 Use Cases................................................. 103 1.7 Translation Related File Formats..................................... 120 2 Developer’s Guide 149 2.1 Translate Styleguide........................................... 149 2.2 Documentation.............................................. 155 2.3 Building................................................. 159 2.4 Testing.................................................. 159 2.5 Command Line Functional Testing................................... 161 2.6 Contributing............................................... 163 2.7 Translate Toolkit Developers Guide................................... 165 2.8 Making a Translate Toolkit Release................................... 169 2.9 Deprecation of Features......................................... 174 3 Additional Notes 177 3.1 Release Notes.............................................. 177 3.2 Changelog................................................ 240 3.3 History of the Translate Toolkit..................................... 248 3.4 License.................................................. 249 4 API Reference 251 4.1 API.................................................... 251 Python Module Index 535 i ii Translate Toolkit Documentation, Release 2.0.0 Welcome to Translate Toolkit’s documentation. This documentation covers both user’s and programmer’s perspective. Contents 1 Translate Toolkit Documentation, Release 2.0.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 2.0.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 several Linux distributions, the package might be available through your package manager. On Windows, we recommend using a virtual environment. If your system already has the toolkit prepackaged, then please let us know what steps are required to install it. 1.2.1 Building For build instructions, see the Building page. 1.2.2 Download Download a stable released version. Or if you have a python environment, run pip install translate-toolkit. For those who need problems fixed, or who want to work on the bleeding edge, get the latest source from Git. If you install through your distribution’s package manager, you should automatically have all the dependencies you need. If you are installing a version from Version Control, 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.3 Installing packaged versions Get the package for your system: 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: $ 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 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. 4 Chapter 1. User’s Guide Translate Toolkit Documentation, Release 2.0.0 1.2.4 Installing on Windows On Windows we recommend that you install Translate Toolkit using a virtual environment. This makes installation clean and isolated. Use the latest Python 2.7 (at least Python 2.7.9 or newer as it bundles the pip installer). Install virtualenvwrapper-win to simplify handling of virtualenvs. 1. Install latest Python 2.7 2. Open cmd.exe or similar 3. pip install virtualenvwrapper-win 4. mkvirtualenv ttk where “ttk” is the name for the new virtualenv 5. pip install translate-toolkit to install latest stable or pip install –pre translate-toolkit to try a pre-release 6. pip install “lxml>=3.5” to be able to use XLIFF or other XML formats 7. po2prop –version to double check you have the right version Next times you need to use Translate Toolkit just remember to: 1. Open cmd.exe or similar 2. workon ttk to enable the virtualenv again 3. Run the Translate Toolkit commands you want 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: $ prop2po --version prop2po 2.0.0 1.2. Installation 5 Translate Toolkit Documentation, Release 2.0.0 1.2.7 Cleaning up existing installation To remove old versions of the toolkit which you might have installed without a virtual environment or without your package manager. The following advice only applies to manual installation from a tarball. 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 -R /usr/local/lib/python2.7/dist-packages/translate 1.3 Converters 1.3.1 General Usage The tools follow a general usage convention which is helpful to understand. Input & Output The last two arguments of your command are the input and output files/directories: moz2po <input> <output> You can of course still use 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. 6 Chapter 1. User’s Guide Translate Toolkit Documentation, Release 2.0.0 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. in oo2po we are converting to Gettext PO Getting Help The --help option will always list the available commands for the tool. moz2po--help 1.3.2 moz2po moz2po converts Mozilla files to PO files.