Language Localization Translation
From PHPDevShell
NOTE: as we are moving to Launchpad, all the translation efforts will be much more easier. The documentation will soon reflect this.
PHPDevShell uses the brilliant gettext (po & mo) translation system. This system performs extremely well and is used in many open source systems. PHPDevShell has the capability to completely translate the core system with 3rd party plugins to a different language, this without influencing how the developer should develop.
We have had very little support from the community willing to translate PHPDevShell. Thus the only current languages available are English and French. The whole translation system is already in place though, if you are willing to translate PHPDevshell to another language please don't hesitate, translation is easy with our new launchpad implementation! Please see: https://translations.launchpad.net/phpdevshell
PHPDevShell's developers chose to use the GNU gettext localization framework to provide localization infrastructure to PHPDevShell. gettext is a mature, widely used framework for modular translation of software, and is the de facto standard for localization in the open source/free software realm. gettext uses message-level translation — that is, every "message" displayed to users is translated individually, whether it be a paragraph or a single word. In PHPDevShell, such "messages" are generated, translated, and used by the PHPDevShell PHP files via two PHP functions. __() and $core->__() is used inside heredoc tags or elsewhere where __() will not work.
This means anything you write inside __('Hello World') or $core->__('FooBar') can be translated to any other language or string. The whole of PHP core is done with this language functions meaning the whole PHPDevShell can be converted. You can develop your plugins in the same way, this will allow your plugin to be available in many languages you choose.
The great thing about this translation technology is that even if a string is missing in the translation it will still translate those that are available.
Contents |
Step 1: Translate your language if not available
If your language is not already translated, you will have to do so yourself, this is very easy though.
- Make sure you read and understand https://help.launchpad.net/Translations/StartingToTranslate
- Click on the link https://translations.launchpad.net/phpdevshell/trunk
- If your language is not listed add your language to the list and see if it was translated already.
- If not translated, simply click on the language name next to the translation package and use the web interface to do the translation.
Step 2: Download and rename translation files
The next process will show you how to download and what to name the downloaded translation packages.
- Click on the link https://translations.launchpad.net/phpdevshell/trunk
- Click on the language of one of the three translation packages.
- Click on download selecting .mo format and repeat the process to download core.lang, plugin.lang, hercules-messages.
- Rename the files like;
- ??_LC_MESSAGES_plugin.lang.mo => PHPDevShell.mo
- ??_LC_MESSAGES_core.lang.mo => core.lang.mo
- ??_LC_MESSAGES_hercules-messages.mo => HerculesPostman.mo
- You will now have 3 renamed .mo files.
Step 3: Prepare and set correct language options in PHPDevShell
You are now ready to make the required settings in PHPDevShell to enable the translation.
- Enable FirePHP to check where templates mo files are being looked for.
- On the same settings page also enable the translated language. Locate "User Registration Settings" under "User Registration Settings" there are two multiple selection boxes called Languages Available and Regions Available. Select the translated language and region and click save, this will then be available for your users to choose from when they register or from their user preferences else falling back to the default language selected seeing that you can also make your translated language your default language in System Settings.
- Select your language and region from your "User Preferences" page for it to activate the correct language lookup.
- You will note the language debug system now display the locations of .mo files it looks for, copy the renamed .mo files to those directories, it should show green if found.
a Typical example of where the system will look for the required .mo files are;
/home/titan/html/phpdev/plugins/HerculesPostman/language/af_ZA/LC_MESSAGES/HerculesPostman.mo /home/titan/html/phpdev/plugins/PHPDevShell/language/af_ZA/LC_MESSAGES/PHPDevShell.mo /home/titan/html/phpdev/language/af_ZA/LC_MESSAGES/core.lang.mo
Note the "af_ZA" that is the language_REGION for your selected language. You can also find this code in your "User Preferences" under "Locale Language, Region and Charset Information", this will form part of the language directory.
Translating Date and Time.
At the moment it is not possible to translate date and time, this is a limitation with the Datetime class of PHP.
Does it not work? Remember these
The gettext framework is sometimes very fragile, there are a few thing to remember when translating, always first try the default settings then;
- The locale must be available on the server it is hosted on for it to work.
- You might need to adjust your locale format for your server in PHPDevShells settings under Combined Locale Language, Region and Charset Format.
- You cannot use a compiled Windows mo file on Linux, if you are going to use it on a Linux server compile it using linux. (Can someone confirm this?)
- Sometimes when you find things that just wont translate properly switching back to default randomly, try restarting Apache. Sounds crazy but it works.
If you are having problems, please take the time and read through these comments http://www.php.net/manual/en/ref.gettext.php, PHPDevShell does its best keeping it exactly like PHP recommends it, but sometimes servers configuration just differs too much.
Thats it!
Thats all there are to it, now users can select their language when they register or in their User Preferences for their local language.
