From B2evolution

So you want to localize (mainly translate) b2evolution to your own language? Here's how to do it with minimum effort by using the gettext system provided by b2evo.

If this is the first time you deal with localization and/or gettext, you may want to read this background information first:

• Introducing i18n and l10n
• Introducing gettext and .PO files

[edit] How to proceed to localize b2evo to your own language

1. Download the latest available release.
2. Check the already available locales. (A locale is identified by a language code followed by a country code. For example en_US and en_GB are different, though similar, locales). The best way is to go to the admin -> settings -> regional. This page will show you all already available locales and their translation completion percentage. (here is an example - Use demouser / demopass to log in.)
   1. If your locale is not listed, proceed with step 3.
   2. If your locale is listed and has a high completion percentage, you should assume there is already someone working on the l10n for this locale.
   3. If your locale is listed but has a low percentage, it may be possible that there once was a translator working on this locale but that he has given up. Open the matching messages.po file (see below) with a text editor and check the dates as well as the translators email address. You may want to get in touch with him before deciding to continue the translation. You don't want to end up doing the same job twice...
3. Go to the directory /blogs/locales and create a new folder for the new locale by using the same pattern as the existing folder. The first two letters must be your ISO 639 language code. The last two letters must be your ISO 3166 country code. If there is already a locale similar to yours (same language), you may also copy its folder and rename it. That way, you'll benefit from the existing translations
4. Inside of your locale folder, create a subfolder named LC_MESSAGES. Yes, this is a little funky, but it's a gettext convention. Your translations will be located in this subfolder. Namely, they'll be in a file called messages.po.
5. If you're creating a brand new translation, you have no messages.po file yet. In that case, copy the file messages.pot from /locales to your LC_MESSAGES folder and rename it to messages.po .
6. You could edit the messages.po file by hand but it's much easier with a dedicated tool such as poedit.
   1. poedit runs on Windows as well as Linux and other Unix OSes. You can see from the screenshot how untranslated strings appear in blue, "fuzzy" translations (the ones you're unsure of and the ones automatically genereated when new strings are added to b2evo) appear in yellow, and translated strings appear in white.
   2. poedit will also let you add comments or read those the developer may have provided in the "".POT"" file.
   3. And the best of all: poedit will show you all references of a given string in the source code. Even better, it will open the sources and highlight the occurrences for you. This way, you can really make sure what a string is used for when you're not sure about how to translate it! How cool is that?
7. You now need to activate the locale in b2evolution. Open the file /conf/_locales.php and make the following changes:
   1. add an entry to the $locales array by duplicating an existing entry. Customize the locale, the charset you have used for translation and finaly enter the default date and time formats for your country.
   2. you'll probably want to make the newly added locale your default locale (used in the backoffice and for notification messages). Do this by setting $default_locale. You will also have to update the locale for your user profile.
   3. decide if you want b2evolution to localize with the help of the gettext runtime functions ($use_l10n = 1) or with its own l10n system ($use_l10n = 2). The later is generally better. (Note: there are situations where using the gettext runtime would fail miserably...). We strongly recommend you use the default setting (2).
   4. at the end of the file set $allow_po_extraction = 1;
8. At this time, you should see your localization appear in the regional settings screen. Since you have set $allow_po_extraction = 1, you will see a link named [extract] for each locale. Click to extract the strings for your own locale. (This will create a file name _globals.php in your locale folder.)
9. Your translations should now be active
   1. The blogs on the public pages, however, will be displayed in the language that has been set for them in the blogs configuration forms.
   2. Please note: if you make changes to your .po/.mo files after having used them in b2evolution, you may need to restart your webserver in order to clear gettext's internal cache and see your changes.
10. Please send me your messages.po file as well as the settings you have added to the $locales array. I will integrate them in the next public release.
11. With each new release of b2evolution you'll find your messages.po file automatically updated with new strings that may have appeared in the newer versions of b2evolution. However, the auto update will not be automatically updated in b2evolution since neither the messages.mo, nor the _globals.php file will be updated without your go.

By opening the "".PO"" file with poedit you will only have to translate/edit the new or changed strings and send them back to me.

More on Updating Language Files...

You'll see, once you've installed the tools, localizing b2evolution is really easier than it seems!

[edit] Static pages

There is a second .POT file for the static html help pages that are displayed before the installation. This file is located in CVS:/b2evolution/gettext/langfiles/static.POT . If you have trouble obtaining this file, please ask us. We do not elaborate here because we will be reorganizing the POT files soon.

[edit] Plugins

This has not made it into 1.8, but will work with version 1.9

Plugins that do not get shipped with b2evolution have to provide their own translations.

Inside your plugin's directory (e.g. example_plugin/), create a directory called locales, where you create a subdirectory and a _global.php file therein for each locale that is supported:

  example_plugin/
     locales/
        messages.pot
        de_DE/
           LC_MESSAGES/
               messages.po
           _global.php
        fr_FR/
           LC_MESSAGES/
               messages.po
           _global.php
        ...

To help you generate this, b2evo has a xg.php script in /gettext/xg.php. This does not get shipped with releases, but is available from the CVS Version.

The process to create this is: 1. First the plugin needs a messages.pot (PO-template) file. This gets generated whenever some translation strings in the plugin's source got changed:

 mkdir locales/  # if it does not exist yet
 php -f xg.php CWD extract

2a. Then you'll need a messages.po file for every language (e.g. for de_DE). You'll have to do the following only to init the messages.po file of a language (if there is not already one):

 mkdir -p locales/de_DE/LC_MESSAGES
 msginit -i locales/messages.pot -o locales/de_DE/LC_MESSAGES/messages.po

2b. If there's already a messages.po file for a locale, you can update it from messages.pot. The following will update locales/de_DE/LC_MESSAGES/messages.po:

 php -f xg.php CWD merge de_DE

3. Edit the messages.po file with a normal text editor or tool like poedit or KBabel. You should normally only have to update untranslated or fuzzy strings. 4. Convert the messages.po file to the final _global.php file. The following command will create a new <code>de_DE/_global.php file:

 php -f xg.php CWD convert de_DE

5. Send your updated messages.po and _global.php files to the Plugin maintainer (if you are not maintaining it yourself, of course) 6. Profit!

[edit] Shortcut

Plugins only use the _global.php file, not the messages.pot or messages.po files. The messages files are only important to people who want to translate the Plugin.

So, you do not have to package them with your plugin and if your plugin only has very few strings to be translated, you could even skip the whole procedure above and just create the _global.php files "by hand", in the following way:

<?php
$trans[ 'de_DE' ] = array(
  'Hello world!' => 'Hallo Welt!',
  'Hello moon!' => 'Hallo Mond!',
  ...
);
?>

It's just an array, in fact. But providing the "gettext-Extra-Step" might help your translators a lot, because there are powerful editors for messages.po files available.

[edit] Requirements

1. The locales that your plugin supports, have also to be supported by b2evo and the charset of the _global.php file must be the same as defined there (see /conf/_locales.php).

1. The Plugin has to use the T_() method, e.g. $this->T_('Hello world!'); (and not the global function with the same name).