Language support

Introduction

The following article explains exactly how to add a new language translation to XBMC, and how to maintain/update an an existing language file in XBMC. English is the default language of XBMC so it is the English langauge in the SVN that is always up-to-date, please always base your translations of the latest English langauge file from the SVN. The latest language files for XBMC can be found and download here (link).

The Language Folder

The "language" folder in XBMC contains one directory for each language. Each language folder contains two files, langinfo.xml and strings.xml.

What is langinfo.xml

The langinfo.xml file contains language and region specific localization settings used internally by XBMC. Basically it is the default code page XBMC uses for this language file.

Layout of a langinfo.xml file

<xml>

 <language>
   <charsets>
     <gui>GB2312</gui>
     <subtitle>GB2312</subtitle>
   </charsets>
 
   <dvd>
     <menu>cn</menu>
     <audio>cn</audio>
     <subtitle>cn</subtitle>
   </dvd>
 </language>

</xml>

The <charset> section: <gui>: Specifies the character encoding of everything within XBMC that is not unicode. Eg. id3 tags with none unicode encoding. <subtitle>: Default character encoding of subtitles when using a TTF (True-Type-Font). Choose one encoding for each in the list below. The values may differ if you like.
The <dvd> section: Defines the default languages for DVD-Video menu, audio and subtitle language for the DVDPlayer. Choose one for each entry out of the list of ISO-639 language abbreviations. If the DVD-Video you are playing does not support the language that you specified then it will default to English.

What is strings.xml

This files contains all strings displayed in the user interface of XBMC.

Layout of the strings.xml file

<xml>

 <?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
 <strings>
   <string><id>0</id><value>My Programs</value></string>
   <string><id>1</id><value>My Pictures</value></string>
   <string><id>2</id><value>My Music</value></string>
   <string><id>3</id><value>My Videos</value></string>
   <string><id>4</id><value>TV Guide</value></string>
   <string><id>5</id><value>Settings</value></string>
   .
   .
   .
 </strings>

</xml>

Each string is enclosed in a <string> tag. It contains a tag named <id> with a number xbmc uses to reference a string internally. The <value> tag is the string displayed by xbmc.

Hint: Multi-Line Text-Values
If you want your text-values to span multiple lines, you can insert a new line character in your <value> tag.

For example: <xml>

  <string><id>0</id><value>This will be on the first line
And this will be on the second line</value></string>

</xml>

The encoding attribute of the XML header sets the charset the file is encoded with. See List of charsets of possible values. If you don't know what charset you language uses please follow this link to find out.

Adding a new language to XBMC

If you want to add a new language to xbmc, this is the easiest way to start:
1. Copy the english language folder and name it like the language you want to add. The foldername must be in english
2. Edit the langinfo.xml to the defaults of your language
3. Edit the strings.xml and set the encoding attribute of the xml header to the appropriate of your language
4. Translate the strings in strings.xml. For easier translation you can use our XBMC Translator program.

It is also possible to set the encoding to UTF-8 but then make sure the file is also encoded to UTF-8. (A textfile can be encoded to UTF-8 with the Editor of Windows)

If you have everything ready you can upload your new language files as a patch to Trac (our tracker-system)

Maintaining a language

The English language file (strings.xml) is the master for all language files. From time to time the english language file changes. The file is updated with new strings or existing strings are replaced. You will have to keep track of the changes to the english language file and add them to your file.

How to keep track of changes: From time to time check the xbmc svn repository for updates to the english language file. (the link takes you directly to the english language folder.) Another way is to subscribe to svn changelog (RSS). But be warned you do not only get notified when the language file is updated. All updates to the sourcecode of xbmc are posted in this list!

After you are done you can upload your edited language file as a patch to Trac (our tracker-system)

Related articles in the XBMC online manual

• List of Supported Charsets
• List of language codes (ISO-639:1988)

XBMC Translator

The XBMC Translator tool can be used to easily translate each strings contained in the english language file to other languages.

You may also use the translator on Linux (using wine), see this guide.
On the following link you can find detailed information on using the XBMC Translator.

Notes for developers

XBMC uses UTF-8 as internal character encoding. Please make sure if you add new features to xbmc which depend on external data to convert these to UTF-8 if they aren't already. Use the languagefile from branches/linuxport, since we merge that file into trunk.