[Tutorial] Localization (EN)

[Florian Nücke]

Localization

MegaZine 3 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 MegaZine 3. 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 (","):

Code: (xml)

<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":

Code: (xml)

<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!


Titles

Titles are the tool tip texts that can show when hovering images, areas or videos. 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:

Code: (xml)

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

This works the same for 'vid' and 'area' elements.


Images, videos and sounds

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:

Code: (xml)

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

This works the same for the 'vid' and 'snd' elements.

Localization for titles and images/videos/sounds can be mixed, of course, i.e.

Code: (xml)

<img>
    <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>

is perfectly fine.

Unlike the titles, which get loaded with the xml and are stored all the time, images will be dynamically un- and reloaded as needed (to save bandwidth and memory). When switching from German to English for example, the German images will be unloaded and the English ones to replace the will be loaded in their stead. This will result in pages being blank for a short time when switching languages and the image is replaced, of course.


'nav' Elements

Navigation lists can be localized as well. To avoid excessively deep nesting the syntax is slightly different here:

Code: (xml)

<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, but in contrast to, say, different 'src' attributes for images the language is specified within the entry itself. 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:

Code: (xml)

<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 emailing it to the author, thank you!