Translation

From AADoc

Active Agenda uses PHP's gettext functionality to provide translation of phrases into different languages. Translations apply to all static phrases and messages that appear in the application. Data is not translated, however (we do have some plans for this).

NOTE: I have re-organized the translation catalog into many smaller ones (one 'system' catalog and one for each module). I will need to re-write this page to reflect these changes. In the code repository, look under active_agenda/lang/templates to see all the new .pot files.

Existing translations can be migrated to the new structure - we'll just need to figure out how :-) New translations can use the new catalogs, but will need a new script to build the single binary .mo file.--...aaadmin 09:36, 26 May 2007 (PDT)

Currently there is a Swedish translation (just started) and a Portuguese translation in the works. We welcome more translations.

Contents 1 Technical 1.1 Server setup 2 How to translate 3 Collaboration 4 Notes 4.1 Pipes 4.2 Code substitution marks 4.3 String replacement, printf-style

Technical

Note: When a translation of a phrase is not available (because the translation is incomplete), the English phrase will be displayed.

Server setup

Gettext uses files in the active_agenda/lang folder. The file structure is:

s2a/
  active_agenda/
    lang/
      active_agenda.pot    <-- Template file for translations. Generated from the PHP sources.
      sv_SE/
        LC_MESSAGES/
          active_agenda.mo <-- Binary file with Swedish translations
          active_agenda.po <-- Text file with Swedish translations

In this case, "sv_SE" is the locale "Swedish as used in Sweden" (as opposed to for instance Finland Swedish which is sv_FI).

To install a new language, a new subfolder under lang/ is needed:

es_ES/
  LC_MESSAGES/
    active_agenda.mo <-- Binary file with Spanish translations
    active_agenda.po <-- Text file with Spanish translations

In order to make the new language available to users, a new code may be needed in the code type 138. In the application, go to the Code Types module (Administration/Application/Codes), look up the record with Code Type ID 138 and verify that there is an item with a value that corresponds with your locale.

Now, your new translation will be available to users. Just select it in the Users module and the translations will appear the next time the user logs in.

How to translate

As a translator of Active Agenda, you don't need to be a programmer! What you need is the translation "template" file active_agenda.pot, which contains all the translatable phrases. There are currently over 8000 phrases, so the file is pretty large (several megabytes).

The latest version of the translation template file is here (5.9 MiB download):

The easiest way to work with the translation file is to use an editor, like poEdit (Windows/Linux). In Linux, there is also KBabel.

It is also possible to do the translation with a normal text editor, such as Notepad. This is less optimal but possible. All you need to do is fill in the translations in the active_agenda.pot file and save your file as active_agenda.po (not ".pot").

poEdit will help you enter translations correctly, and provides the ability to enter notes (comments) about each translation, and allows you to mark a translation as "fuzzy". Just like editing with a simple text editor, the end result is a .po file (should be named active_agenda.po), and also the binary converted active_agenda.mo file. These files should be placed on the server as described above.

After you have made some translations, send the file to us and we will include it in the distribution! You do not need to finish translating all the phrases before sending us your file.

Collaboration

Because Active Agenda contains lots of technical terms, it is normal for a person to not know the correct translation of every phrase. Sometimes, an expression is unique to Active Agenda, and a decision must be made about the best way to translate it. Please feel free to contact us if you would like to have a word or phrase explained from a domain perspective.

We have set up a collaboration page for each language. These pages are intended to help translators agree on a standard translation of specific terms. We might also set up email lists for each language.

Collaboration pages:

• Translation/Portuguese
• Translation/Swedish

We can also set up an email discussion list for each language translation project.

Notes

Pipes

Many phrases contain a "pipe" (vertical bar) character, like this:

Field Name|This is an explanation of the field.

The purpose of combining the field name and explanation this way is to make it easier for the translator to determine the best way to translate the phrase. It is of course important to write the translation similarly, including the pipe.

Code substitution marks

Some phrases contain a code substitution mark:

/**placeholderName**/

These phrases are bogus phrases and need not be translated.

String replacement, printf-style

Many phrases contain printf-style string replacement marks, and are replaced at run-time. They are either un-numbered (%s) or numbered (%1$s, %2$s, etc.). These placeholders should be kept in the translated phrase. In the example below, %s would be a field name such as "First Name" or "Phone Number":

English:

The field '%s' may not be empty.

Swedish:

Fältet "%s" måste fyllas i.