Sonos Music API - Getting Started Guide

Strings and Localization

Use XML string tables to localize your music service.

XML String TABLE

Every music service implementation must include a URL that points to an XML string table. Enter this URL in the "Technical Configuration" section on the version set up form. Note that this URL should not exceed 64-characters.

The format of the XML string table is as follows:

<?xml version="1.0" encoding="utf-8" ?>
<stringtables xmlns="http://sonos.com/sonosapi">
    <stringtable rev="1" xml:lang="en-US">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="da-DK">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="de-DE">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="es-ES">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="fr-FR">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="it-IT">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="ja-JP">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="nb-NO">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="nl-NL">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="pt-BR">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="sv-SE">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
    <stringtable rev="1" xml:lang="zh-CN">
        <string stringId="ServicePromo">Promo text</string>
    </stringtable>
</stringtables>

This file requires one string table for every language supported by Sonos, shown below:

Language Code Language
en-US English
da-DK Danish
de-DE German
es-ES Spanish
fr-FR French
it-IT Italian
ja-JP Japanese
nb-NO Norwegian
nl-NL Dutch
pt-BR Brazilian Portuguese
sv-SE Swedish
zh-CN Chinese (simplified)

ServicePromo

It highly recommended that your service include a string ID named "ServicePromo" for each language. This string is presented to the Sonos user as they are taken through the music service setup wizard. See the highlighted text below for a sample ServicePromo.

Single or Series of String Identifiers

You can specify a ServicePromo using a single string identifier or a series. Either way, the result is the same. The following is an example of a ServicePromo using a single string identifier (the dots indicate all of the other strings in your strings file):

Single string identifier
<stringtable rev="1" xml:lang="en-US">
...
    <string stringId="ServicePromo">First sentence. Second sentence.</string>
...
</stringtable>

If a string table contains a series of string identifiers, each with an increasing numeric suffix, then each of these strings will be concatenated into a single string.

Series of string identifiers
<stringtable rev="1" xml:lang="en-US">
...
    <string stringId="ServicePromo">First sentence. </string>
    <string stringId="ServicePromo2">Second sentence.</string>
...
</stringtable>

Whether you use a single string or a series, the result will be the same as the series of strings will be concatenated.

Localization

Use the strings table to localize:

Localization of Metadata

Strings that are returned as part of metadata elements (from getMetadata) should be available in multiple languages from the service provider.

Most track and album metadata is naturally based on ID3 tags or similar metadata found in the actual audio file, so these should be presented in their un-localized form. However, if a music service provides a hierarchy of containers or other custom elements, some of these will have names that should be localized.  For example, if a music service provides a collection called “Recommended Artists”, this string will need to be localized for the language preference of the user. The Sonos client will use the HTTP header “Accept-Language” to convey the user’s language preference, following IETF RFC2616, section 14.4.

Example HTTP request header for Spanish

ACCEPT-LANGUAGE: es-ES, es, en-US;q=0.9, en;q=0.8

This specifies that the user is requesting Spanish (Spain) as the first preference, any Spanish as a second choice, and that English is acceptable if Spanish is not supported.

Including metadata in strings

You can include metadata in strings using display types. See the Configuring Lines section of the Configuring Display Types tutorial for details.