[rkward-cvs] SF.net SVN: rkward-code:[5003] trunk/rkward/doc/rkwardplugins/index.docbook

tfry at users.sf.net tfry at users.sf.net
Wed Nov 12 19:35:15 UTC 2014

Revision: 5003
Author:   tfry
Date:     2014-11-12 19:35:14 +0000 (Wed, 12 Nov 2014)
Log Message:
Finish documenting i18n-functionality (for now).

Modified Paths:

Modified: trunk/rkward/doc/rkwardplugins/index.docbook
--- trunk/rkward/doc/rkwardplugins/index.docbook	2014-11-11 14:05:52 UTC (rev 5002)
+++ trunk/rkward/doc/rkwardplugins/index.docbook	2014-11-12 19:35:14 UTC (rev 5003)
@@ -349,6 +349,10 @@
 		These elements are the counterpart to the <command><varselector></command>. They represent <quote>slots</quote> into which the user can put variables. You will note that the <parameter>source</parameter> is set to the same value as the <parameter>id</parameter> of the <command><varselector></command>. This means, the <command><varslot></command>s will each take their variables from the varselector. The <command><varslot></command>s also have to be given an <parameter>id</parameter>. They may have a <parameter>label</parameter>, and they may be set to <parameter>required</parameter>. This means that the <guibutton>Submit</guibutton> button will not be enabled until the <command><varslot></command> holds a valid value. Finally the <parameter>type</parameter> attribute is not interpreted yet, but it will be used to take care that only the correct types of variables will be allowed in the <command><varslot></command>.
+	<para>
+		In case you are wondering about the <parameter>i18n_context</parameter>-attribute: This is to provide context to help the correct translation of the word "against", used as the
+		<command><varslot></command>'s label, but does not affect the functionality of the plugin, directly. More on this in <link linkend="i18n_general">a separate chapter</link>.
+	</para>
 						<radio id="hypothesis" label="using test hypothesis">
 							<option value="two.sided" label="Two-sided"/>
@@ -540,17 +544,19 @@
 	<sect2 id="sect_JS_printout"><title>printout()</title>
 function printout () {
-	echo ('rk.header ("Two Variable t-Test")\n');
+	echo ('rk.header (' + i18n ("Two Variable t-Test") + ')\n');
 	echo ('rk.print (res)\n');
-			And this was all there is to the printout function in most cases. <function>rk.header()</function> prints a standard headline for the results. You can also add some more information to this, if you like, e.g.:
+			And this was all there is to the printout function in most cases. <function>rk.header()</function> prints a standard headline for the results. Note that in the .js files, you have to
+			mark up all translatable strings by hand, using <command>i18n()</command>, or some alternative commands. More on this in the <link linkend="i18n_js">chapter on internationaliation</link>.
+			You can also add some more information to this, if you like, e.g.:
 function printout () {
-	makeHeaderCode ("Two Variable t-Test", new Array ("Assume equal variances",
-		getString ("varequal"), "Confidence level", getString ("conflevel")))
+	makeHeaderCode (i18n ("Two Variable t-Test"), new Array (i18n ("Assume equal variances"),
+		getBoolean ("varequal.state") ? i18n ("yes") : i18n ("no"), i18n ("Confidence level"), getString ("conflevel")))
 	echo ('rk.print (res)\n');
@@ -597,7 +603,8 @@
 			Statements in a lower block should be indented with one tab (see example below).
-			If you do very complex calculations, add a comment here and there, esp. to mark up logical sections.
+			If you do very complex calculations, add a comment here and there, esp. to mark up logical sections. Note that there is a dedicated function <command>comment()</command> for inserting
+			translatable comments in the generated code.
 			For example, generated code might look like this. The same code without indentation or comments would be pretty hard to read, despite its modest complexity:
@@ -628,9 +635,9 @@
 	echo ('x <- <' + getString ("x") + ')\n');
 	echo ('results <- list ()\n');
-	if (getBoolean ("domean.state")) echo ("results$'Mean value' <- mean (x)\n");
-	if (getBoolean ("domedian.state")) echo ("results$'Median' <- median (x)\n");
-	if (getBoolean ("dosd.state")) echo ("results$'Standard deviation' <- sd (x)\n");
+	if (getBoolean ("domean.state")) echo ("results$" + i18n ("Mean value") + " <- mean (x)\n");
+	if (getBoolean ("domedian.state")) echo ("results$" + i18n ("Median") + " <- median (x)\n");
+	if (getBoolean ("dosd.state")) echo ("results$" + i18n ("Standard deviation") + " <- sd (x)\n");
@@ -801,8 +808,8 @@
 					<option value="variable" checked="true" label="another variable (select below)"/>
 					<option value="constant" label="a constant value (set below)"/>
-				<varslot id="y" types="number" source="vars" required="true" label="variable"/>
-				<spinbox id="constant" initial="0" label="constant" />
+				<varslot id="y" types="number" source="vars" required="true" label="variable" i18n_context="Noun; a variable"/>
+				<spinbox id="constant" initial="0" label="constant" i18n_context="Noun; a constant"/>
@@ -909,7 +916,7 @@
 		<tab [...]>
-		<tab label="Plot Options">
+		<tab label="Plot Options" i18n_context="Options concerning the plot">
 			<embed id="plotoptions" component="rkward::plot_options"/>
 		<tab [...]>
@@ -1060,7 +1067,7 @@
 function doCommonStuff () {
 	// perhaps fetch some options, etc.
 	// ...
-	echo ("# This is R code you want in several different plugins\n");
+	comment ("This is R code you want in several different plugins\n");
 	// ...
@@ -1363,7 +1370,7 @@
 		// be generated.
 		if (full) {
-			echo ('rk.header ("An example plot")\n\n');
+			echo ('rk.header (' + i18n ("An example plot") + ')\n\n');
 			echo ('rk.graph.on ()\n');
 		// only the following section will be generated for full==false
@@ -1941,6 +1948,37 @@
 				E.g. if an unsuspecting translator translates a string meant as a variable name in two distinct words with a space in between.
+		<sect2 id="i18n_js_compatibility"><title>i18n and backwards compatibility</title>
+			<para>
+				One unfortunate aspect of the lack of <command>i18n()</command>-support in &rkward; versions up to 0.6.2 is that adding <command>i18n()</command> calls will make the plugin require
+				&rkward; version 0.6.3. If your plugin is developed outside &rkward;'s official release, this may be a problem. Here are some possible options on how to handle this:
+			</para>
+		<itemizedlist>
+			<listitem><para>Provide the plugin in two versions for &rkward; >= 0.6.3 and &rkward; < 0.6.3, as described in the chapter on 
+					<link linkend="sect_dependencies_rkward_version">handling dependencies</link></para></listitem>
+			<listitem><para>Simply don't translate the strings in the .js-file, yet. Obviously this is an easy, but rather inelegant solution.</para></listitem>
+			<listitem><para>Include some support code in your .js-file(s) like shown below:</para></listitem>
+		</itemizedlist>
+		<programlisting>
+			// js-function "comment" was not defined before 0.6.3
+			if (typeof (comment) == 'undefined) {
+				// define function i18n(), and any others you may need. Note that your implementation could actually be simpler than
+				// shown, here, e.g. if you do not make use of placeholders.
+				i18n = function (msgid) {
+					var ret = msgid;
+					for (var i = 1; i < arguments.length; i++) {
+						ret = ret.replace(new RegExp("%" + i, 'g'), arguments[i]);
+					}
+					if (msgid.noquote) {
+						ret.noquote = msgid.noquote;
+						return (ret);
+					}
+					return (noquote (quote (ret)));
+				}
+			}
+		</programlisting>
+		</sect2>
 	<sect1 id="i18n_workflow"><title>Translation maintainance</title>
@@ -1962,12 +2000,27 @@
 					<replaceable>xx</replaceable> is the language code, again).</para></listitem>
 			<listitem><para>You should also include the non-compiled translation (i.e. <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command>) in
 					your distribution, in the "po" subdirectory.</para></listitem>
+			<listitem><para>For any update of your plugin, run <command>python scripts/extract_plugin_messages.py /path/to/my.pluginmap</command> to update the .pot file, but also the
+					existing .po-files.</para></listitem>
 	<sect1 id="i18n_translators"><title>Writing plugin translations</title>
-			Workflow and guidelines
+			We assume you know your trade as a translator, or are willing to read up on it, elsewhere. A few words specifically about translations of RKWard plugins, though:
+		<itemizedlist>
+			<listitem><para>RKWard plugins were not translatable until version 0.6.3, and were mostly not written with i18n in mind, before then. Thus you are going to encounter rather
+					more ambiguous strings, and other i18n problems than in other mature projects. Please don't just silently work around these, but let us (or the plugin maintainers) 
+					know, so we can fix these issues.</para></listitem>
+			<listitem><para>Many RKWard plugins refer to highly specialized terms, from data handling and statistics, but also from other fields of science. In many cases, a good translation
+					will require at least basic knowledge of these fields. In some cases, there <emphasis>is</emphasis> no good translation for a technical term, and the best option may 
+					be to leave the term untranslated, or to include the English term in parentheses. Don't focus too much on the 100% mark of translated strings, focus on providing 
+					a good translation, even if that means skipping some strings (or even skipping some message catalogs as a whole). Other users may be able to fill in any gaps in technical
+					terms.</para></listitem>
+			<listitem><para>At the time of this writing, &rkward;'s project hosting is about to change, and this also affect the translation workflow. Do read comments accompanying 
+					the .pot-files, on how translations should be handled. If in doubt, it is never wrong to send your work the the rkward-devel mailing list, or to ask for up-to-date instructions,
+					there.</para></listitem>
+		</itemizedlist>

More information about the rkward-tracker mailing list