From 266a3e46516f6f5d49284b3784d6e92bf178bad4 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sun, 1 Sep 2024 14:26:32 +0200 Subject: [PATCH] Documentation update --- CHANGELOG.md | 6 ++ FAQ-ANDROID.md | 4 +- THEMES-DEV.md | 234 ++++++++++++++++++++++++++++++++++++++++++----- TRANSLATIONS.md | 13 ++- USERGUIDE-DEV.md | 8 ++ 5 files changed, 241 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 98d3fc137..dd3a5a435 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,9 +43,11 @@ * (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 * 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 +* Added support for including theme files from within the colorScheme and fontSize tag pairs * Game files with only an extension and no filename will now get skipped on application startup * StringUtil::toCapitalized() will now capitalize text more accurately by using ICU boundary analysis * Removed some obsolete code from DateTimeEditComponent @@ -64,6 +66,10 @@ * When returning from a game the helpsystem was sometimes using the dimmed theme properties * The StringUtil::toCapitalized() function didn't correctly capitalize multi-byte Unicode characters * (Windows) Video textures were sometimes not sized and aligned correctly horizontally +* The theme engine game count text was capitalized by default instead of being set as lowercase +* Text elements defined as gamecount using the systemdata property could not scroll horizontally +* (linear-es-de) The system logo and carousel icon for saturnjp was incorrectly showing the western variant +* (modern-es-de) The carousel icon for saturnjp was incorrectly showing the western variant * There was a typo where the 32:9 aspect ratio was referred to as 32:0 ## Version 3.0.3 / 3.0.3-26 diff --git a/FAQ-ANDROID.md b/FAQ-ANDROID.md index 14f086244..e114a873d 100644 --- a/FAQ-ANDROID.md +++ b/FAQ-ANDROID.md @@ -106,9 +106,9 @@ Another option that could speed up startup times under some circumstances is dis In summary huge game collections are discouraged on Android due to limitations in the operating system itself. Setting up a collection of tens of thousands of games is for sure achievable with ES-DE on Linux, macOS or Windows but it's not really feasible on Android. -## On game launch RetroArch runs an old game instead of the one I just selected, how do I prevent this? +## On game launch the emulator runs an old game instead of the one I just selected, how do I prevent this? -There is a video on the official ES-DE YouTube channel on how to configure RetroArch correctly so that it quits completely when you're exiting a game:\ +You need to exit the game every time you stop playing, by doing this everything will work correctly. Pressing the home button or manually navigating back to ES-DE without exiting the game is equivalent to pressing "Alt+tab" on a desktop operating system, i.e. the game will still run. The difference from desktop operating systems is that Android pauses the game if you switch away from its window so it may seem like it has closed down, although it actually hasn't. While the procedure to fully exit a game differs between emulators there's a video on the official ES-DE YouTube channel on how to configure RetroArch correctly so that it quits completely when you're exiting a game:\ https://www.youtube.com/watch?v=k5WWacfIn6Y ## What type of Android devices are supported diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 2c57f2c5b..98801a438 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -97,7 +97,7 @@ 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: @@ -386,7 +386,7 @@ emulationstation --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. @@ -407,12 +407,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. @@ -742,6 +742,182 @@ 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 | 简体中文 | + +These languages are currently getting translated and may be supported in the near future: + +| Language | English name | Native name | +| :------------ | :----------------------- | :----------------------- | +| de_DE | German | Deutsch | +| el_GR | Greek | Ελληνικά | +| nl_NL | Dutch | Nederlands | +| ar_EG | Arabic | العربية | + + +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 + + + + Developer + Publisher + + + + + Utvecklare + Utgivare + + + + + + 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.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.88 0.511 + 0.165 0.03 + ${langLabelDeveloper} + + + 0.88 0.5935 + 0.165 0.03 + ${langLabelPublisher} + + + +``` + ## 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. @@ -900,9 +1076,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. @@ -914,19 +1090,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 @@ -934,7 +1120,8 @@ The structure of the file is simple, as can be seen in this example: - + + true noMedia @@ -944,7 +1131,8 @@ The structure of the file is simple, as can be seen in this example: - + + true noMedia @@ -959,7 +1147,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 `