Use an XML string table to localize and change text strings for your music service in the Sonos app.

---

XML string table

Every music service implementation must include a URL that points to an XML string table. This URL should not exceed 64-characters. Enter this URL in the “Technical Configuration” section on the version set up form. See Submit your service for details. The format of the XML string table should be:

Include one string table for every language supported by Sonos, including:

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)

The Sonos app maps the stringId in the strings.xml file to a StringId or OnSuccessStringId in the presentation map. Here’s an example:

In the example above, the THUMBS_DOWN StringId will map to the value in the THUMBS_DOWN stringId in the strings.xml file. Likewise, the VOTEDOWNSUCCESS OnSuccessStringId maps to the VOTEDOWNSUCCESS stringId. The Sonos app uses the strings in the following presentation map fields for the actions below:

• The OnSuccessStringId as the toast message when the event completes.
• The StringId for voice over text.
• The Sonos app for Mac or PC also uses the StringId for mouse-over text.

The StringId should correspond to the stringId defined in the strings.xml file. SMAPI uses StringId values in many APIs, usually pre-pended with a descriptor, such as OnSuccessStringId. See the objects and parameters in the available Sonos Music API methods for strings available in each API.

Add strings for accessibility

The Sonos app uses strings for accessibility features, such as voiceover or talkback. Be sure use stringId values in all cases, specific to the actual usage of the action, to help with accessibility. For example, instead of:

use:

Provide a value that…

• Briefly describes the element.
• Does not include the type of the control or view. The type information is contained in the traits attribute of the element and should never be repeated in the label.
• Begins with a capitalized word. This helps VoiceOver read the label with the appropriate inflection.
• Does not end with a period. The label is not a sentence and therefore should not end with a period.
• Is localized. Be sure to make your application available to as wide an audience as possible by localizing all strings, including accessibility attribute strings. In general, VoiceOver speaks in the language that the user specifies in international settings.

See Apple Accessibility Programming Guide for IOS for details.

Add strings for all languages supported by Sonos

Add strings for the languages above, even if your service is not offered in all of the locales above. This will ensure that a Sonos listener with their device set to a different language will be able to use your service in their language. For example, if your service is intended only for a US audience, you should still have strings for Spanish, because some users in the US may have their devices configured to that language. If you only have en-US strings defined, they will only see and hear English strings, regardless of their device settings.

No new lines

Be sure the string types that the Sonos app displays to the user don’t include newlines (“/n”). For example, string types such as “title”, “artist”, and “album.” We recommend that you test how the Sonos app displays these strings during development.

---

ServicePromo

Your service requires a string ID named “ServicePromo” for each language.

The Sonos app presents this string to the listener as they go through the content 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):

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:

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:

• Ratings. If your service implements ratings, then you will need to populate entries in this table for the various ratings prompts and feedback messages. See strings in Configure ratings for details.
• Custom error handling. If you require custom messages in certain error cases, then you will need to populate entries in this table for each custom error. See Error handling for details.
• Customized Info View. If your service has customized any actions on the Info View screen, you will need to populate entries in this table. See Add actions for details.

Localization of metadata

Strings that are returned as part of metadata elements, such as from getMetadata, should be available in multiple languages from your service.

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 your service provides a hierarchy of containers or other custom elements, some of these will have names that should be localized.  For example, if your service provides a collection called “Recommended Artists”, the Sonos app will need to localize this string for the listener’s language preference. The Sonos app will use the HTTP Accept-Language header to convey the listener’s language preference, following IETF RFC2616, section 14.4.

Example HTTP request header for Spanish

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 Configure display types for details.