App localisation

Page under construction

If you have questions about anything here, feel free to ask in the repo discussions.

---

SpMp has two types of localised strings: App strings and external strings.

App strings

Standard Android-style app strings used for UI, stored in XML files contained in shared/src/commonMain/resources/assets/. Each language has its own 'values' directory under 'assets' containing a 'strings.xml' for the actual string data.

To add a new language

Find the tag for the language here, and create a new 'values' directory inside 'assets', appended with the language tag. For example, the Korean values directory would be 'values-ko-KR'. Then create a 'strings.xml' in that directory and populate it with strings. You may want to copy an existing strings.xml for reference.

Strings marked with translatable="false" should not be included in any strings.xml file except the main one in the blank values folder. If a string's usage is unclear, try searching for its key in the app's source code.

External strings

Because SpMp has separate UI and metadata languages, UI strings from YouTube must be converted back to the UI language using key-value pairs defined in uistrings on the ytm-kt repository.

Technical explanation

When the app retrieves recommendations or song info from YouTube, it can only request a single language for the data to be provided in. This means that because of SpMp's feature of setting separate UI and song metadata languages, data is requested from YouTube in the metadata language rather than the UI language. This data may also come with UI strings, such as for the home recommendations feed, but these strings cannot be used directly because they do not match the app's UI language setting (as they were requested using the metadata language).

To add a new language

Find the tag for the language here, and add it to UILanguages.kt so that it can be referenced when defining strings. Ex. to add Korean, just add the the following line: val ko: String = "ko-KR".

To localise an external string for a given language you must know what the value of that string is in that language. For example, if you wanted to localise the YoutubeHomeFeed.kt string for the "Listen again" row, you could go to the YouTube homepage with your language set to the language you want to add, and find the title text of the listen again row. If the key doesn't match exactly, the string will not be localised.

SpMp external strings are defined in this format:

add( // Add a new string
    en to "Community playlists", // English key and value
    ja to "コミュニティの再生リスト", // Japanese key
    ja to "再生リスト" // Japanese value
)

// By default, all keys are also used as the value for that language (like en in this example)
// To use a value that is different from the key, just include a second string using that language (like ja in this example)

// Example
// SpMp makes a request to YouTube in English (the metadata language) and gets a UI string with value "Community playlists"
// The app cycles through each external string until it finds one with a matching English key
// And then returns the value for that string in the app's UI language (in this case, the second ja value "再生リスト")

Page under construction