Localizing a book

From MegaZine3
Jump to navigation Jump to search


See also: Translations

MegaZine3 supports an easy way to localize books, and to allow users to quickly switch between languages without the need to completely reload the book. It is also not necessary to completely localize every element of the book, but only the ones you need to.

GUI

Many translations for the user interface already come with the releases of MegaZine3. To allow the user to select a certain language use the lang attribute of the book tag. Here you can specify the language's ISO 639-1 code you wish to use. Just make sure there is a translation for that language in the same directory as the megazine.swf file. Translation files are named like this: lang.ID.xml, where ID is the ISO 639-1 code. If you want to allow multiple languages specify more languages by separating the codes by commas (,):

<book lang="de,en,it">

The first language in the list will be used as the default language, unless the system language of the user is found in the list, in which case the system language is used. This behavior (using the system language) can be disabled by setting the ignoresyslang attribute to true:

<book lang="de,en,it" ignoresyslang="true">

Important: when using localized titles, images, etc. always specify the language in the lang attribute of the book!

Elements

In general, all elements are completely localizable. This is achieved by allowing the definition of localized attributes in the form of child nodes.

On the example of the title attribute. Titles are the tool tip texts that can show when hovering elements. To localize a title, do not use the title attribute of the element, but instead create child tags with the name title for each language you need. These in turn have an attribute lang for the language id an contain the text of the title:

<img src="...">
    <title lang="de">Deutscher Tooltip</title>
    <title lang="en">English tool tip</title>
</img>

This works the same for all elements.

Images, videos and sounds, too, can be localized. This can be useful when there are texts in the images or audio in videos that should get localized as well. The pattern is the same as for titles, just that you won't use title as the child tag, but src:

<img>
    <src lang="de">image/german.jpg</src>
    <src lang="en">image/english.jpg</src>
</img>

This works the same for the video and sound elements.

It is possible to use this to localize any attribute at all. For example, it would also be possible to write something like this:

<img>
    <overlay lang="de">color(0.5,1,0xFF0000)</code>
    <overlay lang="en">border(0,1,dotted)</code>
    <src lang="de">image/german.jpg</src>
    <title lang="de">Deutscher Tooltip</title>
    <src lang="en">image/english.jpg</src>
    <title lang="en">English tool tip</title>
</img>

The order of the localized nodes does not matter. If, however, an attribute is found for the same language more than once, the last entry will be used.

When switching between languages all localized elements will be unloaded and then reloaded with the settings for the new language. This will result in pages being blank for a short time when switching languages.

nav Elements

Navigation lists can be localized as well. To avoid excessively deep nesting, here each child node will be looked at seperately, i.e. the element is aware of all its children (and not as normally only the last one found will be used for a certain language).

<nav>
    <lnk lang="en">Entry 1</lnk>
    <lnk lang="en">Entry 2</lnk>
    <lnk lang="de">Eintrag 1</lnk>
    <lnk lang="de">Eintrag 2</lnk>
</nav>

As you can see, all entries will be on the same level. This has the following consequence you have to keep in mind: the order of entries with different languages relative to each other is completely irrelevant. Only the "language internal" order matters. The example from above is therefore equivalent to the following code:

<nav>
    <lnk lang="en">Entry 1</lnk>
    <lnk lang="de">Eintrag 1</lnk>
    <lnk lang="en">Entry 2</lnk>
    <lnk lang="de">Eintrag 2</lnk>
</nav>

It really does not matter how you group the entries, use whatever you find to be more readable.

Conclusion

If the user now chooses a different language via the language chooser in the control bar all titles and elements that have a special representation for that language will be swapped out. If no entry for the language is available the entry in the default language will be displayed.

For images there might occur a certain delay before the new language's version displayed. Titles and navigation lists will be updated instantly.

If you happen to have to translate the GUI texts into your language because there is no translation yet, it would be very much appreciated if you were to contribute the translated XML file to the project by posting it in this wiki, thank you!