晴朗星空下的網絡|The Network under the Bright-Bright Sky

完全使用手冊 (2)

Complete Usage Guide (2)

This page focuses on extending xLanguage in script level, please refer to the previous page for mastering configuration.

Works with Wordpress Multilanguage (MO) file

xLanguage works perfectly with the native Wordpress localization (MO/PO) files, usually those posted in http://codex.wordpress.org/WordPress_in_Your_Language, as well as those published by the themes and plugins independently.

xLanguage in this role is:

1. select the correct MO file to use according to the language selected.
2. Provide a correct localization for the_date(), the_time() calls

First, you would copy those MO files to the places like /wp-content/languages/, /wp-includes/languages/, /wp-content/themes/your_theme/, etc., as instructed by the themes, plugins and WordPress instruction. Second, your MO file name must match the Language Code you picked in the xLanguage settings.

Again, make sure the file name of the MO/PO matches the xLanguage settings. Most, if not all, MO/PO files come wit xx_YY, you must rename them to xx-yy instead. They are case sensitive! For example, if you have defined “en-us” and “zh-hk” for your blog, then the system will look for the “en-us.mo” and “zh-hk.mo” respectively. This is because the browser will based on the language code to do font selection, and they all expect the format xx-xx. xLanguage has no auto detection about the available MO files, and xLanguage will not translate the language code to a proper case during rendering.

If the template functions the_date(), the_time() is called with no parameters, then the value you specified under the Time column and Date column will be used. Note, if you leave them blank, the default one comes with Wordpress will be used instead. Please be aware that quite a lot themes called these functions with parameter, you might want to remove them so xLanguage’s one will be used instead. Customizing the parameter in the MO files is another option. In the backend, the xLanguage accomplishes this by hooking to the pre_option_*_format filter.

Theme Customization

The templates functions are coded in the ‘template.php’ file.

Here are some functions that will return the value described:

• xlanguage_current_language_code()
  Returns the locale code being used within this HTTP request.
• xlanguage_current_language()
  Returns the language name of the locale being used within this HTTP request. The language name itself will go through the localization filter
• wp_localization($content)
  Apply the localization logic (Single line content and preferred way of multi-line parsing). Same as calling apply_filters('localization', $content)

Below are the functions that will output a large block to the browser. To override the default look and feels, please copy the ‘wp-content/plugins/xlanguage/view/xlanguage‘ folder to your theme folder, i.e. ‘wp-content/themes/your_theme/view/xlanguage‘, then the template file over there will be used instead.

• xlanguage_post_other_langs()
  This function will display the languages that also written in a particular post. This must be used in the loop.
  <?php if (function_exists('xlanguage_post_other_langs')) xlanguage_post_other_langs(); ?>
  The above code can be inserted in template file like ’single.php’, right after the date line perhaps.
• xlanguage_list_langs()
  This function will display the languages defined to be visible in the configuration, allow user to switch their language preference. Need not to be in the loop.
  Usually, instead of calling this, you just need to use the xLanguage Widget, which actually call this functions too.

Flag Image

Another reason for doing customization is that you might want to include some flag images. In my blog, I couldn’t use flag to represent the language (how could I use flag to distinguish zh-cn and zh-hk?), however flags, most likely, are useful in your case.

http://www.famfamfam.com/lab/icons/flags/ and http://www.crwflags.com/FOTW/FLAGS/wflags.html contains a lot of free tiny flag readily available. Put Customizing the xLanguage’s templates to include the <img src> tag shouldn’t be that difficult. As of v2.0.1, simply upload the flags to /wp-contents/theme/YOUR_THEME/view/xlanguage/images as xx.png and xx-active.png and they should work! (Refer to /wp-contents/plugins/xlanguage/view/xlanguage/images for placement and naming convention, the plugin will actually do a search in theme folder, then in the plugin folder)

Widget Title Customization

You might have already found that Single Line Syntax does not work on the widgets’ title. In fact, most widgets’ title is not passed to any filter and hence nothing can be done without modifying the code.

Wordpress 2.6.1 or later, and with standard or updated Widgets

Chance is that you are using some widgets which would pass the title to the widget_title filter, at least the standard one does.

To enable the filtering aginst those widgets’ title. Go to update the Filter Hooks, on the 3rd page of xLanguage options, to include “widget_title” in the “textsingle” filter.

Wordpress 2.6 or eariler, or with outdated Widgets

widget_title is still new, and it could take some time for all those thousands of widgets to get updated. The good thing is that, hacking the code is usually a relative easy task —

1. Open the php file that contains the widget code
2. locate the widget code responsible for rendering, usually the handling function is specified by the wp_register_sidebar_widget invoked in the code.
3. In the rendering function found, locate the $before_title variable.
4. Wrap the title variable with the apply_filters: localization, so it might look like this: apply_filters('localization', $title)
5. Done

By filtering through the localization, xLanguage will do it jobs and apply the filtering logic.

Great thing is that even if you have xLanguage uninstalled later, the code will not breaking the site. Another similar language plugin can also register its own localization filter to provide similar functionality, no solution lock-in. You might want to pushed the author of the widgets to put this line of code into their widgets, so everyone benefits.

Left to Right and Right to Left

RTL language needs a range of tweaks, xLanguage didn’t specially crafted to support it, but things could be done with minimal effort.

If you have prepared a different theme for different languages, you could do so by entering it under the Presentation section in the Advanced page.

If your theme is well designed for both directions, and that the style body { direction: rtl; } is all you needed, you might edit your theme header file to add this conditionally —

1. Open the header.php in your theme files
2. Add the following code —
   <?php if (function_exists('xlanguage_current_language_code') && xlanguage_current_language_code() == 'ar') { ?>
<style type="text/css">
body { direction: rtl; }
</style>
<?php } ?>
3. Of course, the ‘ar’ should be the RTL locale code you have actually used.

Filter Hook

Short answer: In case you need to making your plugin compatible to xLanguage, you need to identify the output points, taking seo-title-tag as an example, its output function is seo_title_tag();

Changing
… if (function_exists(’seo_title_tag’)) { seo_title_tag(); } …
to
… if (function_exists(’seo_title_tag’)) { apply_filters(’localization’, seo_title_tag()); } …

will make it working once nice and great with xLanguage.

Filters are some very handy tools in Wordpress plugin programming, it allows chain of plugins to modify the content at some designated, designed entry point or hook.

This is how xLanguage apply its logic and modify the texts of everything, by attaching to the the known entry points. You are free to modify the hooks that xLanguage attached to, in the Options page.

As mentioned in the Widget Title Customization above, xLanguage does hook to the localization with filtering logic by default. It is not used anywhere in the Wordpress itself, but nevertheless Wordpress does not provide any similar entry point. I would like to promote this hook to be implemented by plugins to provide similar functionalities, and in turns, users and other plugins can rely on this hook too.

Entry was posted on 21 January 2008 at 6:21.

Comment | Commends and pings OK