From a7c1d463ca92d276e80847dc700531fa07a88994 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 9 Sep 2024 19:02:50 +0200 Subject: [PATCH] Documentation update --- ANDROID-DEV.md | 24 ++-- CHANGELOG.md | 20 ++-- INSTALL-DEV.md | 5 + THEMES-DEV.md | 17 ++- THEMES.md | 286 ++++++++++++++++++++++++++++++++++++++++++------ TRANSLATIONS.md | 2 +- 6 files changed, 288 insertions(+), 66 deletions(-) diff --git a/ANDROID-DEV.md b/ANDROID-DEV.md index 3621f31fc..332e57322 100644 --- a/ANDROID-DEV.md +++ b/ANDROID-DEV.md @@ -516,22 +516,14 @@ https://github.com/Vita3K/Vita3K-Android/releases ### Winlator -In order to use Winlator to run Windows games you need to use a specific fork named _Winlator Cmod_ as mainline [Winlator](https://winlator.com/) does not offer frontend support. However the official GitHub page of this fork has disappeared so it's not clear which is the official release and where it can be downloaded from. As there are now multiple builds floating around the Internet you'll need to do some web searches to find a reliable distribution. +In order to use Winlator to run Windows games you need to use a specific fork named _Winlator Cmod_ as mainline [Winlator](https://winlator.com/) does not offer frontend support. The Cmod fork can be downloaded from their GitHub page:\ +https://github.com/coffincolors/winlator -There are two variants of the fork, Glibc and PRoot, both of which comes with some pros and cons with regards to compatibility and performance. +There are two variants of the fork, Glibc and PRoot, both of which come with some pros and cons with regards to compatibility and performance. The Glibc variant is the default emulator in ES-DE, so to use PRoot instead you'll need to select its alternative emulator entry. -The following builds have been successfully tested with ES-DE: +In addition to the official repository there are multiple Winlator builds floating around the Internet, but these have not been extensively tested with ES-DE. -| Filename | Type | MD5 hash | -| :-------------------------------------- | :---- |:-------------------------------- | -| cmod-v6-pre-release-v6fix1.apk | glibc | 678c6edf341f17128b071daa9756c459 | -| Winlator-7.1.3-glibc-cmod-v7fix5.apk | glibc | a3d935d7d09e7999c43511de333efbcc | -| Winlator-7.1.2-proot-cmod-v6.5-BETA.apk | proot | 540fcc6faf1f0938d1bee3c85235d9ed | - - -Consider these as examples only, there may very well be a lot of other builds that work fine with ES-DE. - -It's beyond the scope of this document to describe how to install games in Winlator, but once it's done and you've created a shortcut to your game from inside the container you can export it via the _Export for Frontend_ option in the Winlator user interface. This will generate a .desktop file that you can place in the `ROMs/windows` folder and launch from ES-DE. +It's beyond the scope of this document to describe how to install games in Winlator, but once it's done and you've created a shortcut to your game from inside the container you can export it via the _Export for Frontend_ option in the Winlator user interface. This will generate a .desktop file that you can place in the `ROMs/pcarcade`, `ROMs/type-x` or `ROMs/windows` folder and launch from ES-DE. You can alternatively set the _Frontend Export Path_ setting from inside the Winlator Settings screen to avoid the manual step of moving the .desktop file. ### Yaba Sanshiro 2 @@ -783,7 +775,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | pc | IBM PC | DOSBox-Pure | DOSBox-Core,
DOSBox-SVN,
VirtualXT | No | See the specific _DOS / PC_ section in the user guide | | pc88 | NEC PC-8800 Series | QUASI88 | | Yes | | | pc98 | NEC PC-9800 Series | Neko Project II Kai | Neko Project II | | | -| pcarcade | PC Arcade Systems | _Placeholder_ | | | | | +| pcarcade | PC Arcade Systems | Winlator Cmod Glibc **(Standalone)** | Winlator Cmod PRoot **(Standalone)** | No | See the _Winlator_ section elsewhere in this document | | pcengine | NEC PC Engine | Beetle PCE | Beetle PCE FAST,
Beetle SuperGrafx,
PCE.emu **(Standalone)** | No | Single archive or ROM file | | pcenginecd | NEC PC Engine CD | Beetle PCE | Beetle PCE FAST,
Beetle SuperGrafx,
PCE.emu **(Standalone)** | Yes | | | pcfx | NEC PC-FX | Beetle PC-FX | | Yes | | @@ -832,7 +824,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | to8 | Thomson TO8 | Theodore | | | | | triforce | Namco-Sega-Nintendo Triforce | _Placeholder_ | | | | | trs-80 | Tandy TRS-80 | _Placeholder_ | | | | -| type-x | Taito Type X | _Placeholder_ | | | | +| type-x | Taito Type X | Winlator Cmod Glibc **(Standalone)** | Winlator Cmod PRoot **(Standalone)** | No | See the _Winlator_ section elsewhere in this document | | uzebox | Uzebox Open Source Console | Uzem | | | | | vectrex | GCE Vectrex | vecx | MAME4droid 2024 **(Standalone)** | Yes for MAME4droid 2024 | Single archive or ROM file | | vic20 | Commodore VIC-20 | VICE xvic | | No | Single archive or tape, cartridge or diskette image file | @@ -843,7 +835,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file | | wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,
Dolphin MMJR **(Standalone)**,
Dolphin MMJR2 **(Standalone)** | No | | | wiiu | Nintendo Wii U | _Placeholder_ | | | | -| windows | Microsoft Windows | Winlator Glibc Cmod **(Standalone)** | Winlator PRoot Cmod **(Standalone)** | No | See the _Winlator_ section elsewhere in this document | +| windows | Microsoft Windows | Winlator Cmod Glibc **(Standalone)** | Winlator Cmod PRoot **(Standalone)** | No | See the _Winlator_ section elsewhere in this document | | windows3x | Microsoft Windows 3.x | DOSBox-Pure | | No | | | windows9x | Microsoft Windows 9x | DOSBox-Pure | | No | | | wonderswan | Bandai WonderSwan | Beetle Cygne | Swan.emu **(Standalone)** | No | Single archive or ROM file | diff --git a/CHANGELOG.md b/CHANGELOG.md index 02ab089bb..d82056f32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,13 +8,13 @@ This release brings full localization support and includes translations to ten new languages. More specifically these are Spanish (Spain), French, Italian, Polish, Portuguese (Brazil), Romanian, Russian, Swedish, Japanese and Simplified Chinese. More languages will follow in future releases. -As part of the localization work there have been substantial changes made to the application; text rendering has been improved with proper text shaping using the HarfBuzz library and case mappings and boundary analysis are now performed by the ICU library. +As part of the localization work there have been substantial changes made to the application, for instance to the text rendering which has been improved with proper text shaping using the HarfBuzz library. Case mappings and boundary analysis are now also performed by the ICU library rather than using inaccurate built-in functions as was previously the case. -As for minor but notable improvements, entering the wrong ScreenScraper credentials will now display an error popup during scraping, specific subdirectories inside the system folders can be excluded from getting loaded, and the starting time for the video screensaver has been greatly reduced on devices with poor disk I/O performance, such as Android. +As for other notable improvements, entering the wrong ScreenScraper credentials will now display an error popup during scraping, specific subdirectories inside the system folders can be excluded from getting loaded, and the starting time for the screensaver has been greatly reduced on devices with poor disk I/O performance, such as Android. A number of new systems have also been enabled on Android, which brings game system support for this platform one step closer to being on par with the desktop ports. -The release also brings a new port with experimental support for the Haiku operating system. +And talking of ports, this release also brings experimental support for the Haiku operating system. -See the full list below for all changes like added emulators, launch command modifications and bug fixes. +See the full list below for all changes and bug fixes. ### Detailed list of changes @@ -32,10 +32,12 @@ See the full list below for all changes like added emulators, launch command mod * Added translations for Swedish (sv_SE) * Added translations for Japanese (ja_JP) * Added translations for Simplified Chinese (zh_CN) -* Dramatically improved start times for the video and slideshow screensavers on devices with poor disk I/O performance (like Android) -* Added support for skipping the scanning of game system subdirectories (by using noload.txt files) +* Dramatically reduced the start time for the video and slideshow screensavers on devices with poor disk I/O performance (like Android) +* Added support for skipping game system subdirectories scanning on startup (by using noload.txt files) * Added an error popup if incorrect credentials (username and password) are used when scraping using ScreenScraper * Added a "Dark and red" menu color scheme to improve perceived contrast on low-contrast displays +* (Android) Added support for the PC Arcade Systems (pcarcade) game system using the Winlator emulator +* (Android) Added support for the Taito Type X (type-x) game system using the Winlator emulator * (Android) Added support for the Microsoft Windows (windows) game system using the Winlator emulator * (Android) Added support for the Dragon Data Dragon 32 (dragon32) game system * (Android) Added support for the Tano Dragon (tanodragon) game system @@ -64,7 +66,9 @@ See the full list below for all changes like added emulators, launch command mod * (Android) Added support for using the %BASENAME% variable with the %EXTRA% and %EXTRAARRAY% variables * Text within parantheses is no longer stripped out from the game name popup when adding or removing games from custom collections * Renamed the "Menu opening effect" setting in the UI settings menu to "Menu opening animation" -* (linear-es-de) Added translations for en_US, en_GB and sv_SE +* (linear-es-de) Added translations for all supported languages +* (modern-es-de) Added translations for all supported languages +* (slate-es-de) Added partial translations for all supported languages * Added a "backgroundMargins" property to the datetime element * Added a "backgroundCornerRadius" property to the datetime element * Added a check for whether a text element has a width defined when the container property is set @@ -76,7 +80,7 @@ See the full list below for all changes like added emulators, launch command mod * Added the HarfBuzz library as a dependency * Added the ICU library as a dependency * Refactored large parts of the text and font code -* Added experimental support for building on Haiku +* Added experimental support for the Haiku operating system * Added some improvements for building and running on FreeBSD * Removed support for NetBSD and OpenBSD * Updated SDL to 2.30.7 on Android, Windows, macOS and the Linux AppImage builds diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 6f9d51639..52325797f 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -165,6 +165,11 @@ It could also be a good idea to use the `TSAN_suppressions` file included in the TSAN_OPTIONS="suppressions=tools/TSAN_suppressions" ./es-de --debug --resolution 2560 1440 ``` +On some Linux distributions you need to modify the _vm.mmap_rnd_bits_ kernel runtime parameter or you'll see an error message such as _FATAL: ThreadSanitizer: unexpected memory mapping 0x58bd90d75000-0x58bd90dbe000_ when attempting to start ES-DE. Setting the parameter to 28 should make ThreadSanitizer work correctly. The following is how it's done on Ubuntu: +``` +sudo sysctl vm.mmap_rnd_bits=28 +``` + To enable UndefinedBehaviorSanitizer which helps with identifying bugs that may otherwise be hard to find, build with the UBSAN option: ``` cmake -DCMAKE_BUILD_TYPE=Debug -UBSAN=on . diff --git a/THEMES-DEV.md b/THEMES-DEV.md index b17697226..e98b845f9 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -102,9 +102,9 @@ There are two places that ES-DE can load themes from: An installation path could be something like this: ``` -/usr/share/emulationstation/themes/slate-es-de/ -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/ -C:\Program Files\EmulationStation-DE\themes\ +/usr/share/es-de/themes/ +/Applications/ES-DE.app/Contents/Resources/themes/ +C:\Program Files\ES-DE\themes\ ``` If a theme with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped. @@ -145,7 +145,7 @@ As for more specific changes, the following are the most important ones compared * The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views * When right-aligning the helpsystem using an X origin value of 1, the element is now aligned correctly to the defined position instead of being offset by the entrySpacing width (in RetroPie ES the offset was instead the hardcoded element entry padding) * Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail -* Many additional elements and properties have been added, refer to the [Reference](THEMES-DEV.md#reference) section for more information +* Many additional elements and properties have been added, refer to the reference section for more information Attempting to use any of the legacy logic in the new theme structure will make the theme loading fail, for example adding the _extra="true"_ attribute to any element. @@ -298,8 +298,7 @@ This is the element structure: ``` -Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the -[Reference](THEMES-DEV.md#reference) section. Properties are defined like this: +Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the reference section. Properties are defined like this: ```xml valueHere @@ -381,7 +380,7 @@ If you are writing a theme it's recommended to enable the _Debug mode_ setting f Here's an example of launching ES-DE in debug mode at a limited resolution, which will make it run in a window: ``` -emulationstation --debug --resolution 1280 720 +es-de --debug --resolution 1280 720 ``` Enforcement of a correct theme configuration is quite strict, and most errors will abort the theme loading, leading to an unthemed system. In each such situation the log output will be very clear of what happened, for instance: @@ -396,7 +395,7 @@ Sanitization for valid data format and structure is done in this manner, but ver Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelistBadges" defined as "leftr" ``` -Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the [Reference](THEMES-DEV.md#reference) section of this document for valid values for each property. +Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the reference section of this document for valid values for each property. For more serious issues where it does not make sense to assign a default value or auto-adjust the configuration, an error log entry is generated and the element will in most instances not get rendered at all. Here's such an example where the imageType property for a video element was accidentally set to _covr_ instead of _cover_: @@ -1461,7 +1460,7 @@ Example `navigationsounds.xml` file: ## Element rendering order using zIndex -You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the [Reference](THEMES-DEV.md#reference) section. +You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the reference section. These are the default zIndex values per element type: diff --git a/THEMES.md b/THEMES.md index d1112ca91..f5e44eeab 100644 --- a/THEMES.md +++ b/THEMES.md @@ -95,14 +95,14 @@ themes/ The ES-DE theme functionality makes it easy for users to install different themes and to choose between them from the _UI Settings_ menu. There are two places that ES-DE can load themes from: -* `[HOME]/.emulationstation/themes/` +* `[HOME]/ES-DE/themes/` * `[INSTALLATION PATH]/themes/` An installation path could be something like this: ``` -/usr/share/emulationstation/themes/slate-es-de/ -/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/ -C:\Program Files\EmulationStation-DE\themes\ +/usr/share/es-de/themes/ +/Applications/ES-DE.app/Contents/Resources/themes/ +C:\Program Files\ES-DE\themes\ ``` If a theme with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped. @@ -143,7 +143,7 @@ As for more specific changes, the following are the most important ones compared * The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views * When right-aligning the helpsystem using an X origin value of 1, the element is now aligned correctly to the defined position instead of being offset by the entrySpacing width (in RetroPie ES the offset was instead the hardcoded element entry padding) * Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail -* Many additional elements and properties have been added, refer to the [Reference](THEMES.md#reference) section for more information +* Many additional elements and properties have been added, refer to the reference section for more information Attempting to use any of the legacy logic in the new theme structure will make the theme loading fail, for example adding the _extra="true"_ attribute to any element. @@ -296,8 +296,7 @@ This is the element structure: ``` -Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the -[Reference](THEMES.md#reference) section. Properties are defined like this: +Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the reference section. Properties are defined like this: ```xml valueHere @@ -379,12 +378,12 @@ If you are writing a theme it's recommended to enable the _Debug mode_ setting f Here's an example of launching ES-DE in debug mode at a limited resolution, which will make it run in a window: ``` -emulationstation --debug --resolution 1280 720 +es-de --debug --resolution 1280 720 ``` Enforcement of a correct theme configuration is quite strict, and most errors will abort the theme loading, leading to an unthemed system. In each such situation the log output will be very clear of what happened, for instance: ``` -Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections") +Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/ES-DE/themes/mytheme-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections") ``` Note that an unthemed system means precisely that, the specific system where the error occured will be unthemed but not necessarily the entire theme. The latter can still happen if the error is global such as a missing variable used by all XML files or an error in a file included by all XML files. The approach is to only untheme relevant sections of the theme to be able to pinpoint precisely where the problem lies. @@ -394,7 +393,7 @@ Sanitization for valid data format and structure is done in this manner, but ver Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelistBadges" defined as "leftr" ``` -Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the [Reference](THEMES.md#reference) section of this document for valid values for each property. +Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the reference section of this document for valid values for each property. For more serious issues where it does not make sense to assign a default value or auto-adjust the configuration, an error log entry is generated and the element will in most instances not get rendered at all. Here's such an example where the imageType property for a video element was accidentally set to _covr_ instead of _cover_: @@ -405,12 +404,12 @@ Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "i Error handling for missing files is handled a bit differently depending on whether the paths have been defined explicitly or via a variable. For explicitly defined paths a warning will be logged for element properties and an error will be triggered for include files. Here's an example of the latter case: ``` -Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/.emulationstation/themes/mytheme-es-de/colors_dark.xml") +Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/ES-DE/themes/mytheme-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/ES-DE/themes/mytheme-es-de/colors_dark.xml") ``` However, if a variable has been used to define the include file, only a debug message will be generated if the file is not found: ``` -Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/.emulationstation/themes/mytheme-es-de/amiga/colors.xml" +Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/ES-DE/themes/mytheme-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/ES-DE/themes/mytheme-es-de/amiga/colors.xml" ``` It works essentially the same way for element path properties as for include files. This distinction between explicit values and variables makes it possible to create a theme configuration where both include files and files for fonts, images, videos etc. will be used if found, and if not found a fallback configuration can still be applied so the system will be themed. @@ -740,6 +739,202 @@ Here's an example configuration: ``` +## Languages + +Multilingual support works very similarly to color schemes and font sizes in that it's a variable-based configuration. Due to this you can set any arbitrary property values you want for a certain language, such as different texts or different images and so on. The supported languages for use in themes are the same as for the overall application. + +Note that the word _language_ is not technically the correct term as it's rather _locales_ that are used within ES-DE. For instance the en_US and en_GB locales are both for the English language but rather variations for different countries (United States and United Kingdom). Still, as the term _language_ is colloquially used to describe locales in many applications and operating systems this is also used in ES-DE even if it's not entirely correct. The term _language_ is as such also used throughout this document. + +While it's possible to use the theme engine language support to set language-specific date formats this is generally discouraged as it's better to use the ISO 8601 (YYYY-MM-DD) standard instead. This is an international standard that makes sense to use in all countries in the world. + +The following languages are supported: + +| Language | English name | Native name | +| :------------ | :----------------------- | :----------------------- | +| en_US | English (United States) | English (United States) | +| en_GB | English (United Kingdom) | English (United Kingdom) | +| es_ES | Spanish (Spain) | Español (España) | +| fr_FR | French | Français | +| it_IT | Italian | Italiano | +| pl_PL | Polish | Polski | +| pt_BR | Portuguese (Brazil) | Português (Brasil) | +| ro_RO | Romanian | Română | +| ru_RU | Russian | Русский | +| sv_SE | Swedish | Svenska | +| ja_JP | Japanese | 日本語 | +| zh_CN | Simplified Chinese | 简体中文 | + +Note that the native name is what is shown inside the _UI Settings_ menu for the _Theme Language_ and _Application Language_ settings. + +You can find more information about locales/languages here:\ +https://simplelocalize.io/data/locales + +The languages a theme supports need to be declared in the `capabilities.xml` file using `` tag pairs, such as the following example: + +```xml + + + My theme + + en_US + es_ES + pt_PR + sv_SE + zh_CN + + +``` + +Although language support is optional for a theme, if you have declared at least one language then you have to include support for en_US as well. Attempting to skip an entry for this language will output an error message and the language configuration will not get loaded. The reason for this is that en_US is the default language for the ES-DE application so all themes have to support it, either implicitly (by not having any multilingual support) or explicitly by declaring it and providing localization for it. + +It's also possible to provide label translations for variants, color schemes and transitions, as displayed in the _UI Settings_ menu. This is done using the `language` attribute for these `label` entries, as in this example `capabilities.xml` file: + +```xml + + My theme + + en_US + sv_SE + + + + + + + + + + true + + noMedia + miximage, screenshot, cover, video + noGameMedia + + + + + + + true + instant + slide + instant + slide + slide + slide + + +``` + +Leaving out the `language` property will make ES-DE set the language to en_US. + +The actual language-specific values in the theme configuration are defined using variables, like the following example: + +```xml + + + + logo.svg + Developer + Publisher + + + + + logo-sv-se.svg + Utvecklare + Utgivare + + + + + + 0.38 0.1781 + 0.158 0.12 + ./assets/${langLogo} + + + 0.88 0.511 + 0.165 0.03 + ${langLabelDeveloper} + + + 0.88 0.5935 + 0.165 0.03 + ${langLabelPublisher} + + + +``` + +It could also be a good idea to include the translations from a separate file: +```xml + + ./languages.xml + + + + 0.38 0.1781 + 0.158 0.12 + ./assets/${langLogo} + + + 0.88 0.511 + 0.165 0.03 + ${langLabelDeveloper} + + + 0.88 0.5935 + 0.165 0.03 + ${langLabelPublisher} + + + +``` + +Including separate files per language is also supported but it's probably not a good idea as it will add a lot of unnecessary files to the theme: +```xml + + + ./lang-en-us.xml + + + ./lang-sv-se.xml + + + + + 0.38 0.1781 + 0.158 0.12 + ./assets/${langLogo} + + + 0.88 0.511 + 0.165 0.03 + ${langLabelDeveloper} + + + 0.88 0.5935 + 0.165 0.03 + ${langLabelPublisher} + + + +``` + +Note the naming convention when using localized versions of files such as images. These should include the locale/language in their name and they should be in lowercase characters, using only dashes as separators. For the default language the locale could be omitted from the filename (as language-specific images and similar will likely be exceptions with most files rather shared across all locales). Here are some examples: + +``` +logo.svg +logo-fr-fr.svg +logo-pt-br.svg +logo-sv-se.svg +auto-allgames.webp +auto-allgames-fr-fr.webp +auto-allgames-pt-br.webp +auto-allgames-sv-se.webp +``` + ## Aspect ratios The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries. @@ -898,9 +1093,9 @@ Finally it's possible to apply theme-defined transition profiles on a per-varian ## capabilities.xml -Variants, variant triggers, color schemes, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme configuration files and that is done in the `capabilities.xml` file. This file needs to be located in the root of the theme directory, for example: +Variants, variant triggers, color schemes, font sizes, languages, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme configuration files and that is done in the `capabilities.xml` file. This file needs to be located in the root of the theme directory, for example: ``` -~/.emulationstation/themes/mytheme-es-de/capabilities.xml +~/ES-DE/themes/mytheme-es-de/capabilities.xml ``` The capabilities.xml file is mandatory and if it doesn't exist ES-DE will not attempt to load the theme. @@ -912,19 +1107,29 @@ The structure of the file is simple, as can be seen in this example: My theme + en_US + sv_SE + 16:9 4:3 4:3_vertical + medium + large + - + + - + + + + instant slide instant @@ -932,7 +1137,8 @@ The structure of the file is simple, as can be seen in this example: - + + true noMedia @@ -942,7 +1148,8 @@ The structure of the file is simple, as can be seen in this example: - + + true noMedia @@ -957,7 +1164,8 @@ The structure of the file is simple, as can be seen in this example: ``` -The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes, one transition animation profile and three variants, one of which is a variant trigger override. The `