Localization/Concepts/Transcript - Revision history

Ilic: New method: warnputs().

2011-08-18T07:56:25Z

New method: warnputs().

Neverendingo: Text replace - "`" to ""`


2011-06-29T21:12:28Z
Text replace - "<code text>" to "<syntaxhighlight lang="text">"

				
				
				
				
			
			← Older revision
			Revision as of 21:12, 29 June 2011
			
Line 295:
Line 295:
    
  Property map files are text files in a simple dictionary format for writing down phrases with their properties (filenames must end in <tt>.pmap</tt>). The format is best shown on the example:   Property map files are text files in a simple dictionary format for writing down phrases with their properties (filenames must end in <tt>.pmap</tt>). The format is best shown on the example:
− <code text> + <syntaxhighlight lang="text">
  # cities.pmap   # cities.pmap
  =:Athens:Atina:nom=Atina:gen=Atine:dat=Atini:acc=Atinu::   =:Athens:Atina:nom=Atina:gen=Atine:dat=Atini:acc=Atinu::
Line 311:
Line 311:
    
  Using a configuration file located at {{path|$HOME/.transcriptrc}}, the user can be allowed to configure certain aspects of Transcript operation. The configuration file is in ini-style, where group names are language codes to which the selections apply. For example:   Using a configuration file located at {{path|$HOME/.transcriptrc}}, the user can be allowed to configure certain aspects of Transcript operation. The configuration file is in ini-style, where group names are language codes to which the selections apply. For example:
− <code text> + <syntaxhighlight lang="text">
  # Settings for German.   # Settings for German.
  [de]   [de]
Line 412:
Line 412:
  === Labels Dependent on Dynamic Values ===   === Labels Dependent on Dynamic Values ===
  Sometimes the text of a standalone label should grammatically conform to the a changing value elsewhere in the interface. The typical example of this is when a sentence-like row of different widgets is used to specify an action:   Sometimes the text of a standalone label should grammatically conform to the a changing value elsewhere in the interface. The typical example of this is when a sentence-like row of different widgets is used to specify an action:
− <code text> + <syntaxhighlight lang="text">
  Search in files modified:   Search in files modified:
  ( ) ...   ( ) ...



Neverendingo: Text replace - "" to ""

2011-06-29T21:09:21Z
Text replace - "<code po>" to "<syntaxhighlight lang="text">"

				
				
				
				
			
			← Older revision
			Revision as of 21:09, 29 June 2011
			
Line 38:
Line 38:
  In Nevernessian it is impolite to speak a greeting with the same tone of voice throughout; instead, the name of the person must be shouted out. Hence, the translator wants to capitalize the placeholder substitute in the following login greeting in {{path|neverness.po}}:   In Nevernessian it is impolite to speak a greeting with the same tone of voice throughout; instead, the name of the person must be shouted out. Hence, the translator wants to capitalize the placeholder substitute in the following login greeting in {{path|neverness.po}}:
    
− <code po> + <syntaxhighlight lang="text">
  #: neverness_login.cpp:10   #: neverness_login.cpp:10
  msgid "Hello, %1!"   msgid "Hello, %1!"
Line 45:
Line 45:
  So the translator adds a scripted msgstr, with an interpolation:   So the translator adds a scripted msgstr, with an interpolation:
    
− <code po> + <syntaxhighlight lang="text">
  #: neverness_login.cpp:10   #: neverness_login.cpp:10
  msgid "Hello, %1!"   msgid "Hello, %1!"
Line 77:
Line 77:
  One problem frequently encountered is use of the wrong noun case when the placeholder is substituted in the msgstr. For example, in many languages every KDE app has such a problem in the Help menu, with one or both of "About %1..." and "%1 &Handbook". This can be scripted in {{path|kdelibs.po}} like this:   One problem frequently encountered is use of the wrong noun case when the placeholder is substituted in the msgstr. For example, in many languages every KDE app has such a problem in the Help menu, with one or both of "About %1..." and "%1 &Handbook". This can be scripted in {{path|kdelibs.po}} like this:
    
− <code po> + <syntaxhighlight lang="text">
  msgid "&About %1"   msgid "&About %1"
  msgstr "&O %1"   msgstr "&O %1"
Line 133:
Line 133:
  The app name in KDE's Help menu indeed comes from the app PO file, and it is of course encountered at runtime before the menu strings come into focus. This allows setting the cases of app name in the PO msgstr which contains it. For example, {{path|katepart.po}} contains the "KWrite" string, and the forms could be set at that point:   The app name in KDE's Help menu indeed comes from the app PO file, and it is of course encountered at runtime before the menu strings come into focus. This allows setting the cases of app name in the PO msgstr which contains it. For example, {{path|katepart.po}} contains the "KWrite" string, and the forms could be set at that point:
    
− <code po> + <syntaxhighlight lang="text">
  msgid "KWrite"   msgid "KWrite"
  msgstr "KWrite"   msgstr "KWrite"
Line 347:
Line 347:
    
  For example, Nevernessians need to match the noun case of "baloon" when it is inserted into sentence "I see a %1", and additionally the adjective form of "red" to baloon in "I see a red %1", so they do:   For example, Nevernessians need to match the noun case of "baloon" when it is inserted into sentence "I see a %1", and additionally the adjective form of "red" to baloon in "I see a red %1", so they do:
− <code po> + <syntaxhighlight lang="text">
  msgid "baloon"   msgid "baloon"
  msgstr ""   msgstr ""
Line 421:
Line 421:
    
  The solution is to ask the programmer to make the label refresh on every change of the list box value, and to add a ''dynamic context'' to the label's message (using <tt>inContext</tt> method of <tt>KLocalizedString</tt>). The dynamic context is a key-value string pair which indicates the current list box value; the key and possible values should be documented in the message's context. If the programmer did this properly, the translator should now see in the PO file:   The solution is to ask the programmer to make the label refresh on every change of the list box value, and to add a ''dynamic context'' to the label's message (using <tt>inContext</tt> method of <tt>KLocalizedString</tt>). The dynamic context is a key-value string pair which indicates the current list box value; the key and possible values should be documented in the message's context. If the programmer did this properly, the translator should now see in the PO file:
− <code po> + <syntaxhighlight lang="text">
  msgctxt ""   msgctxt ""
  "Part of logical sentence 'Search in files modified >during the last< "   "Part of logical sentence 'Search in files modified >during the last< "
Line 429:
Line 429:
  </syntaxhighlight>   </syntaxhighlight>
  The translation can now be scripted based on the <tt>last-what</tt> dynamic context:   The translation can now be scripted based on the <tt>last-what</tt> dynamic context:
− <code po> + <syntaxhighlight lang="text">
  msgstr ""   msgstr ""
  "duureeng thee leestee"   "duureeng thee leestee"





Neverendingo: Text replace - "" to ""
2011-06-29T20:57:23Z
Text replace - "</code>" to "</syntaxhighlight>"

				
				
				
				
			
			← Older revision
			Revision as of 20:57, 29 June 2011
			
Line 41:
Line 41:
  #: neverness_login.cpp:10   #: neverness_login.cpp:10
  msgid "Hello, %1!"   msgid "Hello, %1!"
− msgstr "Heelyy, %1!"</code> + msgstr "Heelyy, %1!"</syntaxhighlight>
    
  So the translator adds a scripted msgstr, with an interpolation:   So the translator adds a scripted msgstr, with an interpolation:
Line 50:
Line 50:
  msgstr "Heelyy, %1!"   msgstr "Heelyy, %1!"
  "|/|"   "|/|"
− "Heelyy, $[shout %1]!"</code> + "Heelyy, $[shout %1]!"</syntaxhighlight>
    
  The first thing to note is that, while a bit longer, msgstr is still a proper PO msgstr, which means that it can be edited and processed by the usual PO tools.   The first thing to note is that, while a bit longer, msgstr is still a proper PO msgstr, which means that it can be edited and processed by the usual PO tools.
Line 65:
Line 65:
  }   }
    
− Ts.setcall("shout", capitalize);</code> + Ts.setcall("shout", capitalize);</syntaxhighlight>
    
  Here the function <tt>capitalize</tt> is an ordinary JavaScript function which takes a string argument and returns all-caps version of it.   Here the function <tt>capitalize</tt> is an ordinary JavaScript function which takes a string argument and returns all-caps version of it.
Line 81:
Line 81:
  msgstr "&O %1"   msgstr "&O %1"
  "|/|"   "|/|"
− "&O $[get-case dative %1]"</code> + "&O $[get-case dative %1]"</syntaxhighlight>
    
  The <tt>get-case</tt> interpolation is supposed to get the <tt>dative</tt> case of whatever app name the <tt>%1</tt> happens to be. The Transcript module {{path|kdelibs.js}} contains the definition of <tt>get-case</tt>, as well as the dictionary of cases:   The <tt>get-case</tt> interpolation is supposed to get the <tt>dative</tt> case of whatever app name the <tt>%1</tt> happens to be. The Transcript module {{path|kdelibs.js}} contains the definition of <tt>get-case</tt>, as well as the dictionary of cases:
Line 104:
Line 104:
  addDictCases("KWrite", "KWritea", "KWriteu", "KWrite", "KWriteom");   addDictCases("KWrite", "KWritea", "KWriteu", "KWrite", "KWriteom");
  addDictCases("Konsole", "Konsole", "Konsoli", "Konsolu", "Konsolom");   addDictCases("Konsole", "Konsole", "Konsoli", "Konsolu", "Konsolom");
− ...</code> + ...</syntaxhighlight>
    
  Function <tt>getProperty</tt>, bound to <tt>get-case</tt> call, simply returns the entry from the dictionary of forms. Function <tt>addDictCases</tt> is responsible for adding the static entries (name and its cases) into the dictionary, which is done in the final few lines for all apps of interest.   Function <tt>getProperty</tt>, bound to <tt>get-case</tt> call, simply returns the entry from the dictionary of forms. Function <tt>addDictCases</tt> is responsible for adding the static entries (name and its cases) into the dictionary, which is done in the final few lines for all apps of interest.
Line 114:
Line 114:
  addDictCases("KWrite", "KWritea", "KWriteu", "KWrite", "KWriteom");   addDictCases("KWrite", "KWritea", "KWriteu", "KWrite", "KWriteom");
  addDictCases("Konsole", "Konsole", "Konsoli", "Konsolu", "Konsolom");   addDictCases("Konsole", "Konsole", "Konsoli", "Konsolu", "Konsolom");
− ...</code> + ...</syntaxhighlight>
    
  and use Transcript interface to load this file in the {{path|kdelibs.js}}:   and use Transcript interface to load this file in the {{path|kdelibs.js}}:
Line 123:
Line 123:
  ...   ...
  ...   ...
− Ts.load("appdict");</code> + Ts.load("appdict");</syntaxhighlight>
    
  Note that <tt>Ts.load()</tt> takes filename without extension, and assumes its location is relative to the folder of the parent file (ie. in this case {{path|kdelibs.js}} and {{path|appdict.js}} should be in the same folder).   Note that <tt>Ts.load()</tt> takes filename without extension, and assumes its location is relative to the folder of the parent file (ie. in this case {{path|kdelibs.js}} and {{path|appdict.js}} should be in the same folder).
Line 137:
Line 137:
  msgstr "KWrite"   msgstr "KWrite"
  "|/|"   "|/|"
− "$[set-cases KWritea KWriteu KWrite KWriteom]"</code> + "$[set-cases KWritea KWriteu KWrite KWriteom]"</syntaxhighlight>
    
  The <tt>set-cases</tt> is a ''side-effect'' interpolation: it should set the dictionary entries, but this particular message should in any case use the ordinary translation. Assuming all the definitions from previous example are still in effect, here is how <tt>set-cases</tt> could be defined in {{path|kdelibs.js}}:   The <tt>set-cases</tt> is a ''side-effect'' interpolation: it should set the dictionary entries, but this particular message should in any case use the ordinary translation. Assuming all the definitions from previous example are still in effect, here is how <tt>set-cases</tt> could be defined in {{path|kdelibs.js}}:
Line 146:
Line 146:
       Ts.fallback();        Ts.fallback();
  }   }
− Ts.setcall("set-cases", dynamicSetCases);</code> + Ts.setcall("set-cases", dynamicSetCases);</syntaxhighlight>
    
  In other words, this is little more than a wrapper to "static" <tt>addDictCases</tt> from previous example, but two new elements of Transcript interface appear. First is the <tt>Ts.msgstrf()</tt> function, which returns the finalized ordinary translation (placeholders substituted), and which is needed in this case as the dictionary key. Second is the <tt>Ts.fallback()</tt> function, which signalizes the Transcript engine to disregard the result of the scripted part of msgstr and use the ordinary translation.   In other words, this is little more than a wrapper to "static" <tt>addDictCases</tt> from previous example, but two new elements of Transcript interface appear. First is the <tt>Ts.msgstrf()</tt> function, which returns the finalized ordinary translation (placeholders substituted), and which is needed in this case as the dictionary key. Second is the <tt>Ts.fallback()</tt> function, which signalizes the Transcript engine to disregard the result of the scripted part of msgstr and use the ordinary translation.
Line 299:
Line 299:
  =:Athens:Atina:nom=Atina:gen=Atine:dat=Atini:acc=Atinu::   =:Athens:Atina:nom=Atina:gen=Atine:dat=Atini:acc=Atinu::
  =:Paris:Pariz:nom=Pariz:gen=Pariza:dat=Parizu:acc=Pariz::   =:Paris:Pariz:nom=Pariz:gen=Pariza:dat=Parizu:acc=Pariz::
− </code> + </syntaxhighlight>
  Each entry starts with two characters, <tt>=:</tt> in this example, which may be chosen arbitrarily (but must be non-letters, and non-#), and can change from entry to entry. The first character defines the separator in the property key-value pair, and the second character is the separator of pairs. E.g. the <tt>gen=Atine</tt> segment above is defining the genitive case of the localized form of Athens. The "pairs" which actually lack the property key (first two in the entries above) are considered phrase identifiers. The completely empty pair (<tt>::</tt> in the example) terminates the entry.   Each entry starts with two characters, <tt>=:</tt> in this example, which may be chosen arbitrarily (but must be non-letters, and non-#), and can change from entry to entry. The first character defines the separator in the property key-value pair, and the second character is the separator of pairs. E.g. the <tt>gen=Atine</tt> segment above is defining the genitive case of the localized form of Athens. The "pairs" which actually lack the property key (first two in the entries above) are considered phrase identifiers. The completely empty pair (<tt>::</tt> in the example) terminates the entry.
    
Line 320:
Line 320:
  [it]   [it]
  with-mozzarella = no   with-mozzarella = no
− </code> + </syntaxhighlight>
  Within scripting modules, the configuration values can be fetched using <tt>Ts.getConf*()</tt> series of calls. These calls will automatically look for the configuration fields under the proper language group, as the scripting modules are language-dependent too.   Within scripting modules, the configuration values can be fetched using <tt>Ts.getConf*()</tt> series of calls. These calls will automatically look for the configuration fields under the proper language group, as the scripting modules are language-dependent too.
    
Line 365:
Line 365:
  "|/|"   "|/|"
  "O sii e $[see-red %1] $[see-it %1]"   "O sii e $[see-red %1] $[see-it %1]"
− </code> + </syntaxhighlight>
    
  The <tt>properties</tt> call, which does all the work -- setting properties, setting new calls by property keys -- looks like this:   The <tt>properties</tt> call, which does all the work -- setting properties, setting new calls by property keys -- looks like this:
Line 408:
Line 408:
  // NOTE: You can replace "properties" in the line above with any UTF-8 string,   // NOTE: You can replace "properties" in the line above with any UTF-8 string,
  // e.g. one in your language so that it blends nicely inside POs.   // e.g. one in your language so that it blends nicely inside POs.
− </code> + </syntaxhighlight>
    
  === Labels Dependent on Dynamic Values ===   === Labels Dependent on Dynamic Values ===
Line 417:
Line 417:
  (*) during the last {day|week|month|year}   (*) during the last {day|week|month|year}
  ( ) ...   ( ) ...
− </code> + </syntaxhighlight>
  <tt>( )</tt> stand for radio buttons, and <tt>{...|...|...}</tt> for a list box with several choices. The label <tt>"during the last"</tt> contains the adjective "last", which in some languages needs to have different forms according to the noun it describes (one of the choices from list box). Whenever the list box value changes, the label should change to match it. But this label is a standalone message in the PO file, so based on what can its translation be scripted?   <tt>( )</tt> stand for radio buttons, and <tt>{...|...|...}</tt> for a list box with several choices. The label <tt>"during the last"</tt> contains the adjective "last", which in some languages needs to have different forms according to the noun it describes (one of the choices from list box). Whenever the list box value changes, the label should change to match it. But this label is a standalone message in the PO file, so based on what can its translation be scripted?
    
Line 427:
Line 427:
  "'w' for week, 'm' for month, 'y' for year."   "'w' for week, 'm' for month, 'y' for year."
  msgid "during the last"   msgid "during the last"
− </code> + </syntaxhighlight>
  The translation can now be scripted based on the <tt>last-what</tt> dynamic context:   The translation can now be scripted based on the <tt>last-what</tt> dynamic context:
  <code po>   <code po>
Line 434:
Line 434:
  "|/|"   "|/|"
  "duureeng $[by-context last-what 'd|m' 'thee leestee' 'w|y' 'thaa leestaa']"   "duureeng $[by-context last-what 'd|m' 'thee leestee' 'w|y' 'thaa leestaa']"
− </code> + </syntaxhighlight>
  The <tt>by-context</tt> call takes the context key, followed by pairs of context value matches (regular expressions) and corresponding phrases; in this example, one form is selected for context values <tt>d</tt> and <tt>m</tt>, and another form for <tt>w</tt> and <tt>y</tt>. The definition of this call is:   The <tt>by-context</tt> call takes the context key, followed by pairs of context value matches (regular expressions) and corresponding phrases; in this example, one form is selected for context values <tt>d</tt> and <tt>m</tt>, and another form for <tt>w</tt> and <tt>y</tt>. The definition of this call is:
  <syntaxhighlight lang="javascript">   <syntaxhighlight lang="javascript">
Line 484:
Line 484:
  // NOTE: You can replace "by-context" in the line above with any UTF-8 string,   // NOTE: You can replace "by-context" in the line above with any UTF-8 string,
  // e.g. one in your language so that it blends nicely inside POs.   // e.g. one in your language so that it blends nicely inside POs.
− </code> + </syntaxhighlight>



Neverendingo: Text replace - "" to ""

2011-06-29T20:35:59Z
Text replace - "<code javascript>" to "<syntaxhighlight lang="javascript">"

				
				
				
				
			
			← Older revision
			Revision as of 20:35, 29 June 2011
			
Line 60:
Line 60:
  The call <tt>shout</tt> itself is defined in the Transcript module {{path|neverness.js}}, which contains only these lines:   The call <tt>shout</tt> itself is defined in the Transcript module {{path|neverness.js}}, which contains only these lines:
    
− <code javascript> + <syntaxhighlight lang="javascript">
  function capitalize (str) {   function capitalize (str) {
       return str.toUpperCase();        return str.toUpperCase();
Line 85:
Line 85:
  The <tt>get-case</tt> interpolation is supposed to get the <tt>dative</tt> case of whatever app name the <tt>%1</tt> happens to be. The Transcript module {{path|kdelibs.js}} contains the definition of <tt>get-case</tt>, as well as the dictionary of cases:   The <tt>get-case</tt> interpolation is supposed to get the <tt>dative</tt> case of whatever app name the <tt>%1</tt> happens to be. The Transcript module {{path|kdelibs.js}} contains the definition of <tt>get-case</tt>, as well as the dictionary of cases:
    
− <code javascript> + <syntaxhighlight lang="javascript">
  function getProperty (prop, key) {   function getProperty (prop, key) {
       return _dict_[key][prop];        return _dict_[key][prop];
Line 110:
Line 110:
  This completes the example, but for better modularization, it is also possible split out the dictionary insertion in a separate file, eg. {{path|appdict.js}}:   This completes the example, but for better modularization, it is also possible split out the dictionary insertion in a separate file, eg. {{path|appdict.js}}:
    
− <code javascript> + <syntaxhighlight lang="javascript">
  // appdict.js   // appdict.js
  addDictCases("KWrite", "KWritea", "KWriteu", "KWrite", "KWriteom");   addDictCases("KWrite", "KWritea", "KWriteu", "KWrite", "KWriteom");
Line 118:
Line 118:
  and use Transcript interface to load this file in the {{path|kdelibs.js}}:   and use Transcript interface to load this file in the {{path|kdelibs.js}}:
    
− <code javascript> + <syntaxhighlight lang="javascript">
  // kdelibs.js   // kdelibs.js
  ...   ...
Line 141:
Line 141:
  The <tt>set-cases</tt> is a ''side-effect'' interpolation: it should set the dictionary entries, but this particular message should in any case use the ordinary translation. Assuming all the definitions from previous example are still in effect, here is how <tt>set-cases</tt> could be defined in {{path|kdelibs.js}}:   The <tt>set-cases</tt> is a ''side-effect'' interpolation: it should set the dictionary entries, but this particular message should in any case use the ordinary translation. Assuming all the definitions from previous example are still in effect, here is how <tt>set-cases</tt> could be defined in {{path|kdelibs.js}}:
    
− <code javascript> + <syntaxhighlight lang="javascript">
  function dynamicSetCases (gen, dat, acc, ins) {   function dynamicSetCases (gen, dat, acc, ins) {
       addDictCases(Ts.msgstrf(), gen, dat, acc, ins);        addDictCases(Ts.msgstrf(), gen, dat, acc, ins);
Line 368:
Line 368:
    
  The <tt>properties</tt> call, which does all the work -- setting properties, setting new calls by property keys -- looks like this:   The <tt>properties</tt> call, which does all the work -- setting properties, setting new calls by property keys -- looks like this:
− <code javascript> + <syntaxhighlight lang="javascript">
  // Set properties of the phrase given by the finalized msgstr in the PO file.   // Set properties of the phrase given by the finalized msgstr in the PO file.
  // The arguments to the call are consecutive pairs of keys and values,   // The arguments to the call are consecutive pairs of keys and values,
Line 436:
Line 436:
  </code>   </code>
  The <tt>by-context</tt> call takes the context key, followed by pairs of context value matches (regular expressions) and corresponding phrases; in this example, one form is selected for context values <tt>d</tt> and <tt>m</tt>, and another form for <tt>w</tt> and <tt>y</tt>. The definition of this call is:   The <tt>by-context</tt> call takes the context key, followed by pairs of context value matches (regular expressions) and corresponding phrases; in this example, one form is selected for context values <tt>d</tt> and <tt>m</tt>, and another form for <tt>w</tt> and <tt>y</tt>. The definition of this call is:
− <code javascript> + <syntaxhighlight lang="javascript">
  // Select a phrase according to dynamic context.   // Select a phrase according to dynamic context.
  // The first argument is the context keyword,   // The first argument is the context keyword,



Pippin: /* The Transcript Engine */ grammar corrections
2010-10-29T16:25:53Z
‎The Transcript Engine:  grammar corrections

				
				
				
				
			
			← Older revision
			Revision as of 16:25, 29 October 2010
			
Line 16:
Line 16:
  == The Transcript Engine ==   == The Transcript Engine ==
    
− KDE4 comes ready with a translation scripting system, the ''Transcript''. Several strategic choices were made in its design: + KDE4 comes ready with a translation scripting system, called ''Transcript''. Several strategic choices were made in its design:
    
  * programmers are unaware of scripting, which means that translator can script any message without outside coordination   * programmers are unaware of scripting, which means that translator can script any message without outside coordination
    
− * unless translator wants to script a message, he is faced with familiar, standard Gettext PO environment (i.e. translators too ''can'' be scripting-agnostic) + * unless the translator wants to script a message, he is faced with the familiar standard Gettext PO environment (i.e. translators, too, can ignore scripting)
    
  * scripting is a low-level bolt-on to Gettext environment, to keep existing PO tools in the game   * scripting is a low-level bolt-on to Gettext environment, to keep existing PO tools in the game
    
− * to have enough power for unforeseen needs, a general-purpose scripting language is provided: JavaScript (with extensions for interfacing with Transcript) + * in order to be powerful enough for unforeseen needs, a general-purpose scripting language is provided: JavaScript (with extensions for interfacing with Transcript)
    
  {{note|For comparison, another translation scripting approach taking some different decisions (new translation environment down to the file format, scripting facilities more specialized, etc.) is brewing at http://wiki.mozilla.org/L20n}}   {{note|For comparison, another translation scripting approach taking some different decisions (new translation environment down to the file format, scripting facilities more specialized, etc.) is brewing at http://wiki.mozilla.org/L20n}}
    
− To script a particular message, translator writes short scripting calls into msgstr in the PO file which expand into parts of msgstr (''interpolations''), and JavaScript code which defines these calls into accompanying Transcript module file (eg. {{path|foo.po}} can be augmented with {{path|foo.js}}). + To script a particular message, the translator writes short scripting calls into msgstr in the PO file which expand into parts of msgstr (''interpolations''), and JavaScript code which defines these calls into an accompanying Transcript module file (eg. {{path|foo.po}} can be augmented with {{path|foo.js}}).
    
− In case the application draws translations from several PO files, scripting calls defined in one of the Transcript modules are available in all used PO files. Since every KDE app uses {{path|kdelibs.po}}, calls defined in {{path|kdelibs.js}} are available everywhere. + In case where the application draws translations from several PO files, scripting calls defined in one of the Transcript modules are available in all used PO files. Since every KDE app uses {{path|kdelibs.po}}, calls defined in {{path|kdelibs.js}} are available everywhere.
    
  The scripting process is illustrated by several examples. More detailed explanations of the elements are given in following sections.   The scripting process is illustrated by several examples. More detailed explanations of the elements are given in following sections.
Line 36:
Line 36:
  === A Useless Example ===   === A Useless Example ===
    
− In Nevernessian it is impolite to speak out a greet with the same tone of voice throughout; instead, the name of the person must be shouted out. Hence, the translator wants to capitalize the placeholder substitute in the following login greet in {{path|neverness.po}}: + In Nevernessian it is impolite to speak a greeting with the same tone of voice throughout; instead, the name of the person must be shouted out. Hence, the translator wants to capitalize the placeholder substitute in the following login greeting in {{path|neverness.po}}:
    
  <code po>   <code po>
Line 54:
Line 54:
  The first thing to note is that, while a bit longer, msgstr is still a proper PO msgstr, which means that it can be edited and processed by the usual PO tools.   The first thing to note is that, while a bit longer, msgstr is still a proper PO msgstr, which means that it can be edited and processed by the usual PO tools.
    
− The first part of msgstr is same as before, and called the ''fallback'' in this context: if the scripted part happens to fail in some way, the fallback translation is used. The fallback is followed by the ''fence'' <tt>|/|</tt>, which separates the fallback and scripted translation (and, for that matter, indicates that this message is scripted). + The first part of msgstr is same as before, and called the ''fallback'' in this context: if the scripted part happens to fail in some way, the fallback translation is used. The fallback is followed by the ''fence'' <tt>|/|</tt>, which separates the fallback and scripted translation (and also indicates that this message is scripted).
    
− Finally, there is the scripted translation after the fence. Compared to fallback, it contains the interpolation <tt>$[shout %1]</tt>, which is supposed to evaluate to a capitalized version of the placeholder substitute. It is composed of the call name, <tt>shout</tt>, and one argument to it, the <tt>%1</tt> placeholder which will be replaced by its substitute. The syntax and expansion rules for interpolations are similar to Unix shell. + Finally, there is the scripted translation after the fence. It is different from the fallback in that it contains the interpolation <tt>$[shout %1]</tt>, which is supposed to evaluate to a capitalized version of the placeholder substitute. It is composed of the call name, <tt>shout</tt>, and one argument to it, the <tt>%1</tt> placeholder which will be replaced by its substitute. The syntax and expansion rules for interpolations are similar to Unix shell.
    
  The call <tt>shout</tt> itself is defined in the Transcript module {{path|neverness.js}}, which contains only these lines:   The call <tt>shout</tt> itself is defined in the Transcript module {{path|neverness.js}}, which contains only these lines:
Line 71:
Line 71:
  The link with the PO file is established by the call to <tt>Ts.setcall()</tt> -- the Transcript interface is represented by the property functions of the <tt>Ts</tt> object. In this variant, the <tt>Ts.setcall()</tt> takes the name of the call for the interpolations in the PO messages (a string), and the JavaScript function which will actually be invoked (''bound'' to the call).   The link with the PO file is established by the call to <tt>Ts.setcall()</tt> -- the Transcript interface is represented by the property functions of the <tt>Ts</tt> object. In this variant, the <tt>Ts.setcall()</tt> takes the name of the call for the interpolations in the PO messages (a string), and the JavaScript function which will actually be invoked (''bound'' to the call).
    
− That's it, now the fair Nevernesse folks are greeted properly. + That's it: now the fair Nevernesse folks are greeted properly.
    
  === Basic Case Resolution ===   === Basic Case Resolution ===
    
− One problem frequently encountered is wrong noun case when placeholder is substituted in the msgstr. For example, in many languages every KDE app has such a problem in the Help menu, with one or both of "About %1..." and "%1 &Handbook". This can be scripted in {{path|kdelibs.po}} like this: + One problem frequently encountered is use of the wrong noun case when the placeholder is substituted in the msgstr. For example, in many languages every KDE app has such a problem in the Help menu, with one or both of "About %1..." and "%1 &Handbook". This can be scripted in {{path|kdelibs.po}} like this:
    
  <code po>   <code po>



Pippin: /* Translation Scripting? */ Add in articles, other grammatical fixes
2010-10-29T16:18:41Z
‎Translation Scripting?:  Add in articles, other grammatical fixes

				
				
				
				
			
			← Older revision
			Revision as of 16:18, 29 October 2010
			
Line 8:
Line 8:
  == Translation Scripting? ==   == Translation Scripting? ==
    
− Current state of affairs in localization of user-visible strings (messages) in application interfaces is such that translator is sometimes forced to supply an inadequate translation. This problem typically occurs when a message contains a placeholder to be substituted at runtime, or when two unrelated strings become related by placement in the interface. In either case, the modest requirements of english language on congruence of words in a sentence allow original string to remain grammatically correct, while not so in many other languages. + The current state of affairs in the localization of user-visible strings (messages) in application interfaces is such that the translator is sometimes forced to supply an inadequate translation. This problem typically occurs when a message contains a placeholder to be substituted at runtime, or when two unrelated strings become related by placement in the interface. In either case, the modest requirements of the English language on the congruence of words in a sentence allow the original string to remain grammatically correct, while in many other languages this is not the case.
    
− Translators and programmers sometimes try to work out a change in the code which would provide a more workable alternative. However, this process is difficult, and worse yet, the outcome is still language-dependent: solving the problem for a few languages does not necessarily solve it for all other. + Translators and programmers sometimes try to work out a change in the code which would provide a more workable alternative. However, this process is difficult, and worse yet, the outcome is still language-dependent: solving the problem for a few languages does not necessarily solve it for all of them.
    
− One way to overcome these problems in a more general and compartmentalized manner, is to provide translators with a way to modify translated strings at runtime, depending on the context (eg. particular placeholder substitutes). In other words, to script translation. Translator should be able to operate on any interface string he wishes, while the programmer should not bear any extra burden (or know about translation scripting at all). + One way to overcome these problems in a more general and compartmentalized manner is to provide translators with a way to modify translated strings at runtime, depending on the context (eg. particular placeholder substitutes). In other words, to script translation. The translator should be able to operate on any interface string he wishes, while the programmer should not bear any extra burden (or know about translation scripting at all).
    
  == The Transcript Engine ==   == The Transcript Engine ==



Ilic: Example of dynamic contexts with dependent labels.
2010-07-23T21:53:57Z
Example of dynamic contexts with dependent labels.

				
				
				
				
			
			← Older revision
			Revision as of 21:53, 23 July 2010
			
Line 407:
Line 407:
  Ts.setcall("properties", setMsgstrProps);   Ts.setcall("properties", setMsgstrProps);
  // NOTE: You can replace "properties" in the line above with any UTF-8 string,   // NOTE: You can replace "properties" in the line above with any UTF-8 string,
  + // e.g. one in your language so that it blends nicely inside POs.
  + </code>
  + 
  + === Labels Dependent on Dynamic Values ===
  + Sometimes the text of a standalone label should grammatically conform to the a changing value elsewhere in the interface. The typical example of this is when a sentence-like row of different widgets is used to specify an action:
  + <code text>
  + Search in files modified:
  + ( ) ...
  + (*) during the last {day|week|month|year}
  + ( ) ...
  + </code>
  + <tt>( )</tt> stand for radio buttons, and <tt>{...|...|...}</tt> for a list box with several choices. The label <tt>"during the last"</tt> contains the adjective "last", which in some languages needs to have different forms according to the noun it describes (one of the choices from list box). Whenever the list box value changes, the label should change to match it. But this label is a standalone message in the PO file, so based on what can its translation be scripted?
  + 
  + The solution is to ask the programmer to make the label refresh on every change of the list box value, and to add a ''dynamic context'' to the label's message (using <tt>inContext</tt> method of <tt>KLocalizedString</tt>). The dynamic context is a key-value string pair which indicates the current list box value; the key and possible values should be documented in the message's context. If the programmer did this properly, the translator should now see in the PO file:
  + <code po>
  + msgctxt ""
  + "Part of logical sentence 'Search in files modified >during the last< "
  + "day|week|...'; provides dynamic context 'last-what': 'd' for day, "
  + "'w' for week, 'm' for month, 'y' for year."
  + msgid "during the last"
  + </code>
  + The translation can now be scripted based on the <tt>last-what</tt> dynamic context:
  + <code po>
  + msgstr ""
  + "duureeng thee leestee"
  + "|/|"
  + "duureeng $[by-context last-what 'd|m' 'thee leestee' 'w|y' 'thaa leestaa']"
  + </code>
  + The <tt>by-context</tt> call takes the context key, followed by pairs of context value matches (regular expressions) and corresponding phrases; in this example, one form is selected for context values <tt>d</tt> and <tt>m</tt>, and another form for <tt>w</tt> and <tt>y</tt>. The definition of this call is:
  + <code javascript>
  + // Select a phrase according to dynamic context.
  + // The first argument is the context keyword,
  + // followed by arbitrary numer of pairs of context values and
  + // corresponding phrases, optionally followed by default phrase.
  + //
  + // Context values are actually regular experessions, so that if one phrase
  + // corresponds to several context values, it does not have to be repeated
  + // but its context value can be given e.g. as 'foo|bar|...'.
  + //
  + // If the context was not matched, default phrase is returned if
  + // it was given; otherwise fallback is signaled.
  + //
  + function selectByContext (/* ctxt_key,
  +                              valrx_1, phrase_1, ..., valrx_N, phrase_N
  +                              [, default_phrase] */)
  + {
  +     if (arguments.length < 1) {
  +         throw Error("Selector by context needs at least one argument.");
  +     }
  + 
  +     // Collect context value for the given key.
  +     var ctxtkey = arguments[0];
  +     var ctxtval = Ts.dynctxt(ctxtkey);
  + 
  +     // Match the context and select the corresponding phrase.
  +     var phrase;
  +     for (var i = 1; i < arguments.length; i += 2) {
  +         if (ctxtval.match(RegExp(arguments[i]))) {
  +             phrase = arguments[i + 1];
  +             break;
  +         }
  +     }
  + 
  +     // If context was not matched, select default phrase or signal fallback.
  +     if (phrase == undefined) {
  +         if (arguments.length % 2 == 0) {
  +             phrase = arguments[arguments.length - 1];
  +         } else {
  +             throw Ts.fallback();
  +         }
  +     }
  + 
  +     return phrase;
  + }
  + Ts.setcall("by-context", selectByContext);
  + // NOTE: You can replace "by-context" in the line above with any UTF-8 string,
  // e.g. one in your language so that it blends nicely inside POs.   // e.g. one in your language so that it blends nicely inside POs.
  </code>   </code>



Ilic: New interface method: toLowerFirst.
2008-11-16T12:16:20Z
New interface method: toLowerFirst.

				
				
				
				
			
			← Older revision
			Revision as of 12:16, 16 November 2008
			
Line 248:
Line 248:
  ; <tt>toUpperFirst (''text'')</tt>   ; <tt>toUpperFirst (''text'')</tt>
  : Converts the first letter in the string into upper case, even if the first character in the string is not a letter. Unicode specification is used to determine what a letter is (i.e. works for non-ASCII letters).   : Converts the first letter in the string into upper case, even if the first character in the string is not a letter. Unicode specification is used to determine what a letter is (i.e. works for non-ASCII letters).
  + :: <tt>''text''</tt> string to process
  + : Returns <tt>String</tt>.
  + 
  + ; <tt>toLowerFirst (''text'')</tt>
  + : Converts the first letter in the string into lower case, under same assumptions as for <tt>toUpperFirst</tt>.
  :: <tt>''text''</tt> string to process   :: <tt>''text''</tt> string to process
  : Returns <tt>String</tt>.   : Returns <tt>String</tt>.



Ilic: Change link to PO format article.
2008-09-06T11:36:54Z
Change link to PO format article.

				
				
				
				
			
			← Older revision
			Revision as of 11:36, 6 September 2008
			
Line 2:
Line 2:
  section=[[Localization#Concepts|Concepts]]|   section=[[Localization#Concepts|Concepts]]|
  name=Translation Scripting with Transcript|   name=Translation Scripting with Transcript|
− prereqs=[[Localization/Concepts/PO_Files|The PO Format]]| + prereqs=[[Localization/Concepts/PO_Odyssey|The PO Format]]|
  extread=[http://developer.mozilla.org/en/docs/JavaScript JavaScript Guide and Reference]|   extread=[http://developer.mozilla.org/en/docs/JavaScript JavaScript Guide and Reference]|
  }}   }}

@@ Line 234: / Line 234: @@
 ; <tt>dbgputs (''msg'')</tt>
-: Outputs a debug message in the shell when KDE has been compiled with debug option.
+: Outputs a debug message in the shell. The message is seen only if KDE libraries have been compiled in debug mode.
 :: <tt>''msg''</tt> message string
 : Returns <tt>Undefined</tt>.
 ; <tt>setcallForall (''name'', ''func'', ''obj'')</tt>