From 79146281fdd7af9ab4051c72d3680bcc0d29f4c3 Mon Sep 17 00:00:00 2001 From: klugier Date: Sun, 8 Nov 2020 19:48:16 +0000 Subject: [PATCH] Core, Doc: Internationalization article style modernized. git-svn-id: svn://ultimatepp.org/upp/trunk@15366 f0d560ea-af0d-0410-9eb7-867de7ffcac7 --- uppsrc/Core/srcdoc.tpp/Tutorial_en-us.tpp | 4 +- uppsrc/Core/srcdoc.tpp/i18n_en-us.tpp | 84 +++++++++-------------- 2 files changed, 36 insertions(+), 52 deletions(-) diff --git a/uppsrc/Core/srcdoc.tpp/Tutorial_en-us.tpp b/uppsrc/Core/srcdoc.tpp/Tutorial_en-us.tpp index 1727c6cd5..209e4efaf 100644 --- a/uppsrc/Core/srcdoc.tpp/Tutorial_en-us.tpp +++ b/uppsrc/Core/srcdoc.tpp/Tutorial_en-us.tpp @@ -25,8 +25,7 @@ topic "U++ Core Tutorial"; [{_} [s2;%% U`+`+ Core Tutorial&] [s22; Table of contents&] -[s5; &] -[s0;3 &] +[s0;^`#Chapter`_1^ &] [s0; [^`#Chapter`_1^ 1. Basics]&] [s0; ___[^`#Section`_1`_1^ 1.1 Logging]&] [s0; ___[^`#Section`_1`_2^ 1.2 String]&] @@ -83,6 +82,7 @@ topic "U++ Core Tutorial"; [s0; ___[^`#Section`_7`_6^ 7.6 CoPartition]&] [s0; ___[^`#Section`_7`_7^ 7.7 CoDo]&] [s0; ___[^`#Section`_7`_8^ 7.8 Parallel algorithms]&] +[s0;^`#Section`_7`_8^ &] [s22;:Chapter`_1: 1. Basics&] [s3;:Section`_1`_1: 1.1 Logging&] [s5; Logging is a useful technique to trace the flow of the code diff --git a/uppsrc/Core/srcdoc.tpp/i18n_en-us.tpp b/uppsrc/Core/srcdoc.tpp/i18n_en-us.tpp index 9624ed62f..60303a3dc 100644 --- a/uppsrc/Core/srcdoc.tpp/i18n_en-us.tpp +++ b/uppsrc/Core/srcdoc.tpp/i18n_en-us.tpp @@ -1,10 +1,9 @@ topic "Internationalization and translation files"; -[2 $$0,0#00000000000000000000000000000000:Default] [l288;i704;a17;O9;~~~.992;2 $$1,0#10431211400427159095818037425705:param] [a83;*R6 $$2,5#31310162474203024125188417583966:caption] [b83;*2 $$3,5#07864147445237544204411237157677:title] [b167;a42;C2 $$4,6#40027414424643823182269349404212:item] -[b42;a42;2 $$5,5#45413000475342174754091244180557:text] +[b42;a42;ph2 $$5,5#45413000475342174754091244180557:text] [l288;a17;2 $$6,6#27521748481378242620020725143825:desc] [l321;t246;C@5;1 $$7,7#20902679421464641399138805415013:code] [b2503;2 $$8,0#65142375456100023862071332075487:separator] @@ -19,79 +18,70 @@ topic "Internationalization and translation files"; [l321;b83;a83;*C$7;2 $$17,17#07531550463529505371228428965313:result`-line] [l160;t4167;*C+117 $$18,5#88603949442205825958800053222425:package`-title] [@(128.0.255)2 $$19,0#65874547464505293575048467215454:QTF Chr] +[2 $$0,0#00000000000000000000000000000000:Default] [{_}%EN-US [s2; Internationalization and translation files&] -[s0; To internationalize your application, you need to provide versions +[s5; To internationalize your application, you need to provide versions of string literals in all required languages. In U`+`+, you can do this using translation files.&] +[s5; To mark string literals for translation in sources, you have +to tag them with [* t`_] macro, like&] [s0; &] -[s0; To mark string literals for translation in sources, you have -to tag them with t`_ macro, like&] +[s7; Cout() << t`_(`"Hello world!`");&] [s0; &] -[s7; printf(t`_(`"Hello world!`"));&] -[s0; &] -[s0; This macro is expanded to function that provides translation +[s5; This macro is expanded to function that provides translation of English (more specifically en`-US) text to default language set by SetLanguage function. String literal here is considered to be the key for translation lookup. U`+`+ supports three forms of keys here:&] -[s0; &] -[s0;i150;O0; plain keys are just en`-US texts. Example: t`_(`"Hello +[s5;l128;i150;O0; Plain keys are just en`-US texts. Example: t`_(`"Hello world!`")&] -[s0;i150;O0; context keys consist of context and en`-US text separated -by `\v, where both are parts of key. Example: t`_(`"align`\vTop`"). +[s5;l128;i150;O0; Context keys consist of context and en`-US text +separated by `\v, where both are parts of key. Example: t`_(`"align`\vTop`"). This is useful in cases when context is needed to provide translation.&] -[s0;i150;O0; id keys consist of id and en`-US text separated by `\a, -but only id is used as key in translation lookup. Example: t`_(`"CtrlCoreReport`\a -Report`"). &] -[s0; &] -[s0; Important: t`_ tag can be used with string literals only.&] -[s0; &] -[s0; t`_ macro expands to function call that provides translation +[s5;l128;i150;O0; Id keys consist of id and en`-US text separated +by `\a, but only id is used as key in translation look up. Example: +t`_(`"CtrlCoreReport`\aReport`"). &] +[s5; [/ Important: t`_ tag can be used with string literals only.]&] +[s5; t`_ macro expands to function call that provides translation of given literal. Where this is not acceptable (like in arrays of literals), tt`_ tag can be used `- it is expanded to literal alone and that can be later converted using GetLngString macro.&] -[s0; &] -[s0; Translations are stored in .t files of regular packages. Format +[s5; Translations are stored in .t files of regular packages. Format of this file is rather simple `- it is set of keys followed by translation of keys to required languages. Key is introduced by T`_, translation, translations are introduced by their language codes, e.g.&] [s0; &] -[s0; T`_(`"Sideways`")&] -[s0; csCZ(`"Na šířku`")&] +[s7; T`_(`"Sideways`")&] +[s7; csCZ(`"Na šířku`")&] [s0; &] -[s0; Language codes for other languages may be found in Core, within +[s5; Language codes for other languages may be found in Core, within the lcid.txt file (found in the Languages section).&] -[s0; &] -[s0; TheIDE provides means for manipulating .t files `- in Workspace +[s5; TheIDE provides means for manipulating .t files `- in Workspace menu there is `"Synchronize translation files`" operation. This operation scans all source files of current project and builds map of t`_ tagged string literals and then combines this information with any valid .t files it finds. This operation also allows adding new languages to .t files.&] -[s0; &] -[s0; t. files are always in UTF8 encoding. To change the encoding +[s5; t. files are always in UTF8 encoding. To change the encoding for your file, you can right`-click on the file in TheIDE, and select `'Convert to encoding...`'. Note that if you use Windows Notepad to save the file as UTF`-8, you may need to strip out the BOM that Windows may have included, or you may experience compiling errors.&] -[s0; &] -[s0; TheIDE also maintains translation repository `- it stores ALL +[s5; TheIDE also maintains translation repository `- it stores ALL translations that it meets into this file. Each time .t file is synchronized, TheIDE tries to supply all missing translations from repository and also adds all translation existing in .t file back to repository. This is e.g. great when some source is moved to another package.&] -[s0; &] -[s0; U`+`+ also supports run`-time translations (as opposite to compile`-time +[s5; U`+`+ also supports run`-time translations (as opposite to compile`-time .t files). You can use `-`-export`-tr in any U`+`+ application to force creation of runtime translation file (with .tr extension). Parameters of this flag is 4 letter language code and single letter character set encoding according this table:&] [s0; &] -[s0; &] [ {{1840:8160<330;>1757;f4;h1; [s19;= [C `_]] :: [s0; utf`-8] :: [s19;= [C 0]] @@ -131,47 +121,41 @@ letter character set encoding according this table:&] :: [s19;= [C J]] :: [s0; iso`-8859`-10]}}&] [s0; &] -[s0; example:&] +[s5; example:&] [s0; &] [s7; myapp `-`-export`-tr dede2&] [s0; &] -[s0; will create dede2.tr file (in exe directory on Win32 and user`'s +[s5; will create dede2.tr file (in exe directory on Win32 and user`'s home folder on Posix) ready for translation to deDE in windows`-1252. If translations are already present, they are supplied, otherwise .tr file contains English strings in place of translations.&] -[s0; &] -[s0; It is also possible to output secondary already translated language +[s5; It is also possible to output secondary already translated language to .tr file as comments (e.g. in case that translator cannot understand English, but can understand some other language):&] [s0; &] -[s0; &] [s7; myapp `-`-export`-tr dede2 cscz&] [s0; &] -[s0; Each U`+`+ application performs search for .tr files at startup +[s5; Each U`+`+ application performs search for .tr files at startup and uses them to extend internal translation tables.&] -[s0; &] -[s0; .tr files can be also imported to .t files using TheIDE`'s `"Import +[s5; .tr files can be also imported to .t files using TheIDE`'s `"Import runtime translation`" function of Workspace menu. Note that this function does not add new languages to .t files `- just adds translations to languages added manually.&] -[s0; &] -[s0; When `-`-export`-tr is used without parameter, it exports all +[s5; When `-`-export`-tr is used without parameter, it exports all compile`-time languages. This is useful for maintenance purposes.&] -[s0; &] -[s0; You will need to include the following in [* one of your compiled +[s5; You will need to include the following in [* one of your compiled files (not a header)]:&] [s0; &] [s7; #define TFILE &] [s7; #include &] [s0; &] -[s0; where `'YourProject/YourTranslations.t`' would be a path to +[s5; where [* `'YourProject/YourTranslations.t`'] would be a path to your translations file.&] -[s0; &] -[s0; To set your application`'s language to the user`'s default language, +[s5; To set your application`'s language to the user`'s default language, add the following somewhere early in your application`'s execution:&] [s0; &] -[s7; SetLanguage( GetSystemLNG() );&] +[s7; SetLanguage(GetSystemLNG());&] [s0; &] -[s0; In multithreaded applications this setting works on per`-thread +[s5; In multithreaded applications this setting works on per`-thread basis (since release 5061); threads inherit the language setting of main thread on startup.]] \ No newline at end of file