Sunday, June 2, 2013

Add on Settings and Localization

Introduction

We cover add on settings and localization at the same time, because the two topics are related. It is not possible to define a settings menu without localizing it. We will modify the France 24 add on that was developed earlier to support multiple stream languages, as France 24 streams live in English and Arabic in addition to French. We will give the user the choice of auto playing the France 24 stream in the selected language, or of selecting the desired language every time the add on is started.

Resources

To support settings and localization, we will need to add a resources folder to our plugin. In the resources folder we will need to create a languages folder, containing at least a folder named English and additional folders for each language supported. In our case, we will add French.
Inside each language folder, we will add a strings.xml file, and we will add a settings.xml to the resources folder. Once done, it should look like this:
In the strings.xml files, we define a mapping with an ID, which must be greater than 30000, and a string in the appropriate language:
/resources/English/strings.xml:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<strings>
    <string id="30001">Live Stream</string>
    <string id="30002">Language</string>
    <string id="30003">French</string>
    <string id="30004">English</string>
    <string id="30005">Arabic</string>
    <string id="30006">Ask</string>
    <string id="30007">Change plugin settings...</string>
</strings>
/resources/French/strings.xml:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<strings>
    <string id="30001">Flux en direct</string>
    <string id="30002">Langue</string>
    <string id="30003">Fran&#e7;ais</string>
    <string id="30004">Anglais</string>
    <string id="30005">Arabe</string>
    <string id="30006">Demander</string>
    <string id="30007">Modifier les paramètres de l'extension...</string>
</strings>
We are now ready to define our add-on settings. Our add-on will have just one setting, a rotary selector with four choices, one for each language and one captioned 'Ask' in English, which will cause the add on to display a menu:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>

  <category label="30001">
    <setting id="language" type="labelenum" label="30002" lvalues="30003|30004|30005|30006"  />
  </category>
</settings>

Note that all of the strings in the settings menu are localized, using the ids previously defined in strings.xml. Other types of controls that can be added to a settings dialog are defined here. Even though we have not written any Python code yet, our settings dialog is now available, by right clicking on the add-on icon and selecting Add-on settings:

Using Settings and Localized Strings

We modify default.py to check for the existence of the language setting. If it is not there, we display the settings dialog to have the user select the desired language. If the user has still not made a choice (by pressing Cancel on the settings dialog), we set the language to Ask. If the language is Ask, we display a menu to select the language, otherwise we auto play the stream in the desired language:
addon = xbmcaddon.Addon('plugin.video.france24.fr')

params = util.parseParameters()
if 'language' in params:
    play(params['language'])
else:
    language = xbmcplugin.getSetting(int(sys.argv[1]), "language")
    if language == '':
        addon.openSettings()
        language = xbmcplugin.getSetting(int(sys.argv[1]), "language")
        if language == '':
            language = "Ask"
    if language == "Ask":
        buildMenu()
    else:
        play(language)
We can also localize the strings in our menu. First, we get a reference to a function that will localize our string, which we place in a variable named localize:
addon = xbmcaddon.Addon('plugin.video.france24.fr')
localize = addon.getLocalizedString

We then use the localize function as needed to convert an id to a localized string:
def buildMenu():
    for language in streams:
        util.addMenuItem(localize(streams[language]['id']), util.makeLink({'language':language}), '', addon.getAddonInfo('icon'))
    util.endListing()

The full code to default.py is shown below and the full plugin can be downloaded here:
import xbmcaddon, util
import xbmcplugin, sys

def buildMenu():
    for language in streams:
        util.addMenuItem(localize(streams[language]['id']), util.makeLink({'language':language}), '', addon.getAddonInfo('icon'))
    util.endListing()

def play(language):
    util.playMedia(addon.getAddonInfo('name'), addon.getAddonInfo('icon'), streams[language]['stream'])

streams = {
        'French':
            {
             'stream': 'rtmp://stream2.france24.yacast.net:80/france24_live/fr playpath=f24_livefr app=france24_live/fr', \
             'id': 30003
            },
        'English':
            {
             'stream': 'rtmp://stream2.france24.yacast.net:80/france24_live/en playpath=f24_liveen app=france24_live/en', \
             'id': 30004
            },
        'Arabic':
            {
             'stream': 'rtmp://stream2.france24.yacast.net:80/france24_live/frda playpath=f24_livefrda app=france24_live/frda', \
             'id': 30005
            }
        }

addon = xbmcaddon.Addon('plugin.video.france24.fr')
localize = addon.getLocalizedString
params = util.parseParameters()
if 'language' in params:
    play(params['language'])
else:
    language = xbmcplugin.getSetting(int(sys.argv[1]), "language")
    if language == '':
        addon.openSettings()
        language = xbmcplugin.getSetting(int(sys.argv[1]), "language")
        if language == '':
            language = "Ask"
    if language == "Ask":
        buildMenu()
    else:
        play(language)

Documentation and References

http://wiki.xbmc.org/index.php?title=Addon_Settings

4 comments :

  1. Hi,
    I can't read Handling XML Web service tutorial. It said there is permission problem with my acount. But I can read other tutorial.

    ReplyDelete
  2. Hello! If you are involved in l10n projects, I recommend to evaluate a localization tool like https://poeditor.com/ that is suitable for crowdsourced translation projects. It comes with a simple and intuitive work interface, and can simplify the localization workflow a lot.

    ReplyDelete
  3. thanks for explaining how to translate config.xml, couldn't find that nontrivial way anywhere else!

    ReplyDelete