The Network under the Bright-Bright Sky

Complete Usage Guide (1)

This page focuses on the general usage and xLanguage configuration, while the next page will focus on the code modifying and APIs so to make everything work as a whole.

How to Use

The basic usage is already shown in the options page. One should first added some languages in the options page. Then one can use the toolbar which is available in the rich text editor to tag the text. For single line content, please adopt the single line filtering mode syntax.

Composing Hotkey

You can use Ctrl+Alt+1 (or 2, 3, etc…) to tag the highlighted text or whole paragraph as in the first (second, third, etc) language. Ctrl+Alt+0 to remove the tag. This should come very handy for keyboard-hotkey-lover like me. Last but not least, Ctrl+Alt+Shift+0 (or Ctrl+Alt+` for pre-WP2.5) to toggle the highlight mode.

Language Configuration

Simple binary bilingual configuration

Example: Blog in English and Spanish, while English being the primary.

1. Add two languages.
   1. Code: en, Name: English
   2. Code: es, Name: Español
2. Set en as default.
3. Optionally add fallback for both language in the advanced page. i.e. en fallbacks to es, es fallbacks to en, with appropriate message.
4. Done. Start blogging with two languages.

Biligual configuration with overlapping

Example: Chinese and a localized Chinese dialect like Cantonese. Cantonese reader can read Chinese but general Chinese reader cannot read Cantonese. Blog is mainly done in Chinese, and the page title, tags and categories are only written in Chinese.

1. Add three languages.
   1. Code: xx-zh, Name: ”
   2. Code: zh, Name: Chinese
   3. Code: zh-yue, Name: Cantonese
2. Set zh as default.
3. In advanced page, do the following modification under the Mix & Match section
   1. xx-zh — Show: ”, Available As: ‘zh,zh-yue’, Position: 0
   2. zh — Show: ‘xx-zh,zh’, Available As: ‘zh’, Position: 0
   3. zh-yue — Show: ‘xx-zh,zh-yue’, Available As: ‘zh-yue’, Position: 0
4. Optionally add fallback for the languages in the advanced page.
5. Done. Start blogging. You may or may not tag the content with xx-zh when blogging, but would be useful if you upgrade to triligual later.

Triligual configuration with overlapping

Example: Blog in Chinese, a localized Chinese dialect like Cantonese and English. Cantonese reader can read Chinese but general Chinese reader cannot read Cantonese. Blog is mainly done in Chinese, and the page title, tags and categories are only written in Chinese and English. (Just like this blog!)

1. Add four languages.
   1. Code: xx-zh, Name: ”
   2. Code: zh, Name: 中文|Chinese
   3. Code: zh-yue, Name: 粵語|Cantonese
   4. Code: en, Name: English
2. Set zh as default.
3. In advanced page, do the following modification under the Mix & Match section
   1. xx-zh — Show: ”, Available As: ‘zh,zh-yue’, Position: 0
   2. zh — Show: ‘xx-zh,zh’, Available As: ‘zh’, Position: 0
   3. zh-yue — Show: ‘xx-zh,zh-yue’, Available As: ‘zh-yue’, Position: 0
   4. en — Show: ‘en’, Available As: ‘en’, Position:1
4. Optionally add fallback for the languages in the advanced page.
5. Done. Start blogging. For Chinese content, tag the content with xx-zh. Or zh and zh-yue if you have written separated content for them.

Fallback and Mix & Match

One might ask in the overlapping example given above, why do we need an additional language xx-zh when zh-yue can be fallback to zh and vice versa. The reason is that, if a zh-yue user is reading a xx-zh post, no “zh” options will be shown in the xlanguage_post_other_langs() bar, but if you only relies on fallback, and did the post in zh, the same function will show the zh available as “other_langs”.

Search Engine Optimization

It might be beneficial to present a page with all content to the search engine crawler, and this can be done too!

1. Add a third language, with locale code like ‘all’ (or anything that won’t collide with any other potential code in the world). Set it to be the Search Engine default.
2. In the Advanced page, make the ‘all’ language only available to the Search Engine under Presentation section
3. Under Mix & Match, for the language ‘all’, list all your languages in the ‘Show’ field, list nothing (empty) in the ‘Available As’, and set -1 in the ‘Position’.
4. Now it’s done. You might try it out by modifying one of your User Agent string to a crawler one, such as ‘googlebot/1.0′

Beware that the search engine crawlers are recognized by using the reported User Agent line only, the detection logic is prone to have false positive (Actual User recognized as Search Engine). After weighting the tradeoff, you might want to mark all the other languages to be not available to Search Engine to reduce duplicated content.

Permalink modification, Postfix or Prefix

If you have the Permalinks feature enabled in WordPress (Settings -> Permalinks), and I don’t see any reason why you don’t unless it’s not supported by your host, the language specifier would then appear as part of the link like …/lang/en, instead of in the form of query string “?lang=en”.

Since v1.3.0, You then have the choice to place the specifier at the beginning of the link (the Prefix mode), or the end of the link. (the Postfix mode). The prefix mode is the default for new installation, and presumably should work nicer with other plugins if you ever run into problem. It also looks better and more intuitive. However, it’s a new feature and if you have encountered any bugs due to this, please do let me know.

Parser (XHTML or Square Bracket)

Since v1.1.0, there are two parsers provided so that your content could be tagged in either way to have it recognized and extracted. Personally I prefer XHTML parser, which <span lang=”..”> works great and incorporate with the standard nicely, while Square Bracket (SB) use [lang_...]…[/lang_...] to tag the content, works equally good when XHTML is not an option. Here is the list showing how they are different besides the tagging code used—

1. The XHTML parser uses HTML tag to tag the content, such that the code is not visible to the user and editor, as well as to the WP searching functionality.
2. The XHTML parser requires strict XHTML to work on, otherwise the parser will fail and complain. Some plugins are known to generate invalid XHTML content that can mess up the parse. The SB parser does not have this problem.
3. The XHTML parser relies on the XML parsing provided by PHP, which might not be installed at all. If that’s the case, SB is your only choice.
4. The XHTML parser implementation is very sensitive to the actual PHP-XML parser implementation, which render it not working in untested PHP version. The SB parser is much more stable in this aspect.
5. The XHTML parser can parse nested language tag, while the SB parser does not work with nested the SB tag.
6. In composing mode, the toolbar for XHTML parser have better functionality such as highlighting (in Firefox and IE7 only), and set/unset function.

Currently, if the XHTML parser failed, the cause will be logged in the Parser Log. Please check the log from time to time to see which page is causing the problem.

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

Comment | Commends and pings OK