diff --git a/LCD-Language.md b/LCD-Language.md index c0a61cb..b007544 100644 --- a/LCD-Language.md +++ b/LCD-Language.md @@ -59,17 +59,17 @@ tr|Turkish uk|Ukrainian ## The Problem -All these languages, except English, normally use extended symbol sets, not contained in US-ASCII. Even the English translation uses some Symbols not in US-ASCII. ( '\002' for Thermometer, STR_h3 for '³') And worse, in the code itself symbols are used, not taking into account on what display they are written. [(This is true only for Displays with Japanese charset)](https://github.com/MarlinFirmware/Marlin/blob/Development/Marlin/ultralcd_implementation_hitachi_HD44780.h#L218) On Western displays you'll see a '~' while on Cyrillic an "arrow coming from top - pointing to left," which is quite the opposite of what the programmer wanted.) The Germans want to use "ÄäÖöÜüß", the Finnish at least "äö". Other European languages want to see their accents on their letters too. For other scripts like Cyrillic, Japanese, Greek, Hebrew, ... you have to find totally different symbol sets. +All these languages, except English, normally use extended symbol sets, not contained in US-ASCII. Even the English translation uses some Symbols not in US-ASCII. ( '`\002`' for Thermometer, `STR_h3` for '³') And worse, in the code itself symbols are used, not taking into account the display they're written on. [(This is true only for Displays with Japanese charset)](https://github.com/MarlinFirmware/Marlin/blob/Development/Marlin/ultralcd_implementation_hitachi_HD44780.h#L218) On Western displays you'll see a '`~`' while on Cyrillic an "arrow coming from top - pointing to left," which is quite the opposite of what the programmer wanted.) The Germans want to use "`ÄäÖöÜüß`", the Finnish at least "`äö`". Other European languages want to see their accents on their letters too. For other scripts like Cyrillic, Japanese, Greek, Hebrew, ... you have to find totally different symbol sets. -Until now the problems were ignored widely. The German translation used UTF-8 'ä' and 'ö' and did not care about showing garbage on ALL displays. Russian translators knew their system only works on Cyrillic displays and relied on special LCD routines (LiquidCrystalRus.cpp) to handle UTF-8 - but forgot to implement a proper `strlen()`. +Until now the problems were ignored widely. The German translation used UTF-8 'ä' and 'ö' and did not care about showing garbage on ALL displays. Russian translators knew their system only works on Cyrillic displays and relied on special LCD routines (`LiquidCrystalRus.cpp`) to handle UTF-8 - but forgot to implement a proper `strlen()`. The Japanese translator dealt with two scripts. He introduced a special font for the Full Graphic Displays and made use of the Japanese version of the character displays. Therefore he ended up with two pretty unreadable `language.h` files full of '`\xxx`' definitions. -Other languages either tried to avoid words that included special symbols or ignored the problem and used the basic symbols without the accents, dots, ... whatever. +Other languages either tried to avoid words that included special symbols or ignored the problem and used the basic symbols without the accents, dots... whatever. ## The (Partial) Solution -On a 'perfect' system like Windows or Linux we'd dig out `unifont.ttf` and some code from the libraries and they'd do what we want. But on an embedded system with very limited resources we have to find ways to limit the used space (Just `unifont.ttf` alone is about 12MB!) making some compromise. +On a 'perfect' system like Windows or Linux we'd dig out `unifont.ttf` and some code from the libraries and they'd do what we want. But on an embedded system with very limited resources we have to find ways to limit the used space (Just `unifont.ttf` alone is about 12MB!), requiring some compromise. ### Aims: @@ -87,14 +87,14 @@ On a 'perfect' system like Windows or Linux we'd dig out `unifont.ttf` and some - Declare the needed translations. (`language_xx.h`) - Make strlen() work with UTF8. (`ultralcd.cpp`) - Separate the Marlin Symbols into their own font. (`dogm_font_data_Marlin_symbols.h`) -- Make the fontswitch function remember the last used font. (`dogm_lcd_implementation.h`) -- Make output functions that count the number of written chars and switch the font to Marlin symbols and back when needed. (`dogm_lcd_implementation.h`) (`ultralcd_implementation_hitachi_HD44780.h`) +- Make the fontswitch function remember the last used font. (`ultralcd_impl_DOGM.h`) +- Make output functions that count the number of written chars and switch the font to Marlin symbols and back when needed. (`ultralcd_impl_DOGM.h`) (`ultralcd_impl_HD44780.h`) - Make three fonts to simulate the HD44780 charsets on dogm-displays. With this fonts the translator can check how his translation will look on the character based displays. - Make ISO fonts for Cyrillic and Katakana because they do not need a mapping table and are faster to deal with and have a better charset (less compromises) than the HD44780 fonts. -- Make mapping functions and tables to convert from UTF8 to the fonts and integrate in the new output functions. (utf_mapper.h) -- Delete the not needed any more 'LiquidCrystalRus.xxx' files and their calls in 'ultralcd_implementation_hitachi_HD44780.h'. -- Split 'dogm_font_data_Marlin.h' into separate fonts and delete. (+dogm_font_data_6x9_marlin.h , +dogm_font_data_Marlin_symbols.h, -dogm_font_data_Marlin.h) -- Do a bit of preprocessor magic to match displays - fonts and mappers in 'utf_mapper.h'. +- Make mapping functions and tables to convert from UTF8 to the fonts and integrate in the new output functions. (`utf_mapper.h`) +- Delete the obsolete `LiquidCrystalRus.xxx` files and their calls in 'ultralcd_implementation_hitachi_HD44780.h'. +- Split 'dogm_font_data_Marlin.h' into separate fonts and delete. (+`dogm_font_data_6x9_marlin.h`, +`dogm_font_data_Marlin_symbols.h`, -`dogm_font_data_Marlin.h`) +- Do a bit of preprocessor magic to match displays - fonts and mappers in `utf_mapper.h`. ## Translators handbook - Check if there is already a `language_xx.h` file for your language (-> b.) or not (-> e.) @@ -109,9 +109,9 @@ On a 'perfect' system like Windows or Linux we'd dig out `unifont.ttf` and some - If you want to make use of more than a few symbols outside standard ASCII or want to improve the portability to more different types of displays use UTF-8 input. That means, define another mapper. - When a mapper other than `MAPPER_NON`, UTF-8 input is used. Instead of "`\xE1`" (on a display with Japanese font) or `STR_ae` simply use "ä". When the string is read byte by byte the "ä" will expand to "`\0xC3\0xA4`" or "Я" will expand to "`0xD0\0xAF`" or "ホ" will expand to "`\0xE3\0x83\0x9B`" - To limit memory usage we can't use all of UTF-8 at the same time. We define a subset matching the language or script we use. - - `MAPPER_C2C3` corresponds well with Western-European languages. The possible symbols are listed at [this page](http://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block)). - - `MAPPER_D0D1` corresponds well with the Cyrillic languages. See [this page](http://en.wikipedia.org/wiki/Cyrillic_(Unicode_block)). - - `MAPPER_E382E383` works with the Japanese Katakana script. See [this page](http://en.wikipedia.org/wiki/Katakana_(Unicode_block)). + - `MAPPER_C2C3` corresponds well with Western-European languages. The possible symbols are listed at [this Latin-1 page](http://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block)). + - `MAPPER_D0D1` corresponds well with the Cyrillic languages. See [this Cyrillic page](http://en.wikipedia.org/wiki/Cyrillic_(Unicode_block)). + - `MAPPER_E382E383` works with the Japanese Katakana script. See [this Katakana page](http://en.wikipedia.org/wiki/Katakana_(Unicode_block)). Mapper functions will only catch the 'lead-in' described in the mapper's name. If the input doesn't match the mapper will output a '?' or garbage. @@ -127,7 +127,7 @@ If you get a lot of question marks on the Hitachi-based displays with your new t - Mappers together with the HD44780_fonts use about additional 128 bytes for the mapping_table. - Creating a new language file is not a big thing. Just make a new file with the format 'language_xx.h' or maybe 'language.xx.utf8.h', define a mapper and a font in there and translate some of the strings defined in language_en.h. You can drop the surrounding #ifndef #endif. You don't have to translate all the stings - the missing one will be added by language_en.h - in English - of cause. - If you can't find a matching mapper things will be a bit more complex. With the Hitachi-based displays you won't have big chance to make something useful unless you have one with a matching charset. For a full graphic display - lets take the example of Greek: - - Find a matching charset. (http://en.wikipedia.org/wiki/Greek_and_Coptic) + - Find a matching charset. ([Greek and Coptic](http://en.wikipedia.org/wiki/Greek_and_Coptic)) - Provide a font containing the symbols in the right size. Normal ASCII in the lower 127 places, the upper with your selection. - Write a mapper that catches -in this case- 0xCD to 0xCF and add it to `utf_mapper.h`. - In case of a ISO10646 font we have a `MAPPER_ONE_TO_ONE` and don't have to make a table. @@ -140,7 +140,7 @@ On the 16x2 displays the strings are cut at the end to fit on the display. So it You'll find all translatable strings in `language_en.h`. Strings in `language.h` are for serial output, so don't require any translation. Core error strings must always be in English to satisfy host protocols. -For information about fonts see the `buildroot/share/fonts/README.md` file. +For information about fonts see [`buildroot/share/fonts/README.md` file](/MarlinFirmware/Marlin/tree/1.1.x/buildroot/share/fonts). ## User Instructions