PCSX2 Documentation/Translation Guide
PCSX2 and GNU gettext Translations
PCSX2 uses an enhanced version of the wxWidgets internationalization module, which itself is based around GNU's gettext system. I'll cover the basics of gettext first, and then apply the PCSX2 enhancements afterward.
How gettext Works (sorta)
GNU gettext works by taking a program which is written in English, and finds the matching translated message in a language file (which is what you as a translator would be making). This means that the actual English version of each message is specified directly in the code itself where the message is used, like so:
MessageBox( _('PCSX2 Critical Error'), _('Your game sucks and we refuse to emulate it properly.') );
... in the above example the _() portion is what invokes the GNU gettext translator, and the strings inside the _() are what gettext uses to look up the translation. The translation is stored in a language file which is given a *.mo extension type, and this file is created from a human-readable text database (clled a *.po file) which is typically generated by the gettext tool itself, and then updated by hand by the translator, using a text editor.
Fortunately there are tools now available to make editing .po files easier. The recommended tool for creating and updating .po files is Poedit. It's an open source app that makes using gettext (usually a terse command line tool) almost a pleasurable experience. Since I personally have no earthly idea how to use gettext, and have only ever used Poedit, the rest of this quick tutorial will read as if Poedit is the only way to actually get the job done.
See our Using Poedit page for details on how to download, install, and configure Poedit.
PCSX2-specific Extension: Iconized gettext Identifiers
The gettext system has many conveniences over other methods of internationalization, which typically rely on the use of pre-processor macros or dynamically linked functions that return string values. The main drawback is that this method relies on the exact English representation, including punctuation, which means that even the slightest change to a text string in PCSX2 will break the translation for that string. For most short messages, such as menu items and button labels, this is fine and is in fact desirable behavior. But for longer messages that serve as descriptions of actions or checkbox options, some of which include formating to fit them to the dialog box more neatly, it can be problematic. This is why PCSX2 has an extension to gettext that uses iconized string matching instead ot the usual literal string matching.
How String Iconization Works
For especially long strings (such as dialog box option descriptions), or strings that contain newline or tab formatting, PCSX2 will use an iconized identifier for it's gettext lookup. These are identified in the gettext database of messages via their '!' prefix, which was chosen to help search and sort for these messages. Because this is a special PCSX2 extension to GNU gettext, you will need to reference the PCSX2 source code when translating them. You should probably be referencing source code during translation as a generla habit anyway, since the source code gives good hints as to the context of messages.
When referencing the source code, these iconized translation messages are used like so:
someCheckBox->SetToolTip( pxE( "!ContextTip:SomeOption", L"This is some option which will make your game run a lot faster, but probably makes it uglier too." ) );
The first string is the icon, which reads "!Tooltips:SomeOption". The second string is the current English literal translation. Poedit will show you the iconized version in its messages list, and you will need to open the source code reference for it to see what the current English translation is. It is important that your Poedit options are set up properly so that viewing the PCSX2 program source code works.
Message icons use a somewhat standard naming convention which will help you decide what's important for translating and/or what sort of formatting you should apply to the message. The common classes are:
- Popup - Messages that are popped up to the user for errors or confirmations. Very High Priority!
- Panel - This is a top-level message on a dialog box or panel. These have a high translation priority.
- Tooltip - These are tips that appear over toolbar buttons. Since button images are rarely fully self-explanatory these types of messages should be translated, so they have a high translation priority. (typically most or all such tooltips won't be iconized anyway, but I'm leaving the door open in case some would be better suited as such).
- ContextTip - This is a popup box that gives additional extra information or details about various options on dialog boxes. Because these are usually supplementary to the dialog box option name and top-level description, translating them is not really necessary for someone to use the program. Translation priority is low.
Compile/Generate pot/po/mo file on linux
- A script (generate_pot.sh) is provided to generates all files on linux. The script does the 3 following steps:
- xgettext -> parse all source files then build the several pot files.
- msgmerge -> sync already translated po files with the previous pot generated. It would drop old string, add new ones and fuzzy string which was updated.
- msgfmt -> compile the po files into mo files then install the results into bin/Langs directory.
To update/upload a new translation, it is as easy as copy the new po into the locales directory, call the script, commit the result.
Downloading and Using POT files
The 1.4 stable release POT file pack can be found here: https://github.com/PCSX2/pcsx2/releases/tag/v1.4.0 Download the source code (zip) open the file and follow the path pcsx2-1.4.0/locales/templates
You may also download the POT files individually from our GIT server. POT files are housed in the /locales/templates/ folder. The latest templates for the active trunk/devel branch of PCSX2 can be found here: https://github.com/PCSX2/pcsx2/tree/master/locales/templates. Note that working from the trunk POTs is not recommended, except in cases where it has been quite a while since the latest stable or beta releases, or when the PCSX2 developers have entered Release Candidiate stages for an upcoming stable release. In most other cases you will want to check out a stable release branch instead, and use the templates from that.
As of the last update to this wiki, the latest stable POT file pack is the 1.4.0 release translation POT.
The Multiple POT files in PCSX2
To assist translators, PCSX2 text messages have been split into a handful of different POT files, as follows:
- pcsx2_main - menu items, buttons, and most labels. High priority; most or all of this file should be translated for a translation to be considered useful.
- pcsx2_iconized - iconized notices, popups, and errors. Most of these are also very high priority; and most or all of this file should be translated for a translation to be considered useful.
- pcsx2_tertiary - Context tips, wizards, and other non-critical user interface elements. All of these strings are also in iconized form.
- pcsx2_devel - Strings used only by devel and debug builds of PCSX2. These mostly consist of loggig and menu options available only in development builds (and excluded from release builds for performance reasons), and tooltips associated with them. Translating these items is purely optional -- most people will never know or care about them.
Only the main PO is required for PCSX2 to detect and use a language. Iconized and tertiary POs are optional. For strings in the iconized and tertiary POTs, you will have to reference the source code to obtain the original English text. It is highly recommended that you use Poedit, since it has a very nice code reference feature built-in. All strings in pcsx2_main.pot are standard gettext strings, and can be translated easily using any regular text editor.
Future versions of PCSX2 may divide the POT files differently.
Submitting your contribution
Before starting a translation, please apply for it in this thread (if there has been no other applicant before you): http://forums.pcsx2.net/Thread-Program-and-Guide-translation-applications
When you're done, you will be given the rights to post in the specific forum for the language you translated into in our board. There you can attach either the actual PO file archive you have created, or a patchfile that can be applied against the current svn copy of the translation.
For those of you who are familiar and comfortable with Github: The PCSX2 Team hosts all available translations from our github repository. Available translations and their submission history can be viewed online at https://github.com/PCSX2/pcsx2/tree/master/locales/templates. You can also use an Git tool such as Git for windows to perform more detailed commit history analysis.
Translations are branched according to the releases of PCSX2 that they conform to.