Very long message strings in .po file rkwardplugins.po

Fri Jan 27 11:05:05 UTC 2017

Hi!

Thanks a lot for your feedback, and sorry about the grief we're
causing! I was in fact totally unaware of this issue, so far (we had
worried quite a bit about making it easier to translate rkward plugins,
but never spent a thought on i18n of the technical documentation).

In essence, the (most) problematic areas appear to the
<programlisting/> elements, and we use those quite a lot. Much of the
content of those areas is actually not translatable, of course, but
there are comments (and some labels) in between, which should be
translated. As a matter of fact, I think(TM), that almost all of those
comments and labels could reasonably be treated as separate translation
units, totally ignoring all the XML surrounding them in the
<programlisting/>s.

Hmm. Do you happen to know just how I could change the markup to
achieve just that?

Regards
Thomas

On Fri, 27 Jan 2017 11:36:55 +0100
Jaap Woldringh <jjhwoldringh at ziggo.nl> wrote:
> First, let me introduce myself:
> 
> I am the Dutch translator of rkward, and am now translating the 
> rkwardplugin.po file.
> 
> Several of the messages are very tedious to translate, but that's in
> the game when translating a handbook. I am not complaining about
> that, though many messages could have been written less longwindedly.
> Clearer for the reader, easier to  translate. Fortunately for me, is
> that now often I can translate the English sentences into Dutch in
> shorter, sometimes much shorter, sentences.
> 
> What I am complaining of is messages like message #195 in said .po
> file, which for your convenience, and as an illustration of what I am
> talking about, I copy here, between ========- lines, and of which you
> don't have to read all lines, of course (just count them):
> 
> =============
> 
> <!DOCTYPE rkhelp>\n
> <document>\n
>          <summary>\n
> In this section, you'll put some short, very basic information about
> what the plugin does.\n
> This section will always show up on the very top of the help page.\n
>          </summary>\n
> \n
>          <usage>\n
> The usage section may contain a little more practical information. It
> does not explain all\n
> the settings in detail (that's done in the "settings" section),
> however.\n \n
> To start a new paragraph, insert an empty line, as shown above.\n
> This line, in contrast, will be in the same paragraph.\n
> \n
> In all sections you can insert some simple HTML code, such as
> <b> bold</b> or\n
> <i>italic</i> text. Please keep formatting to the minimum
> needed, however.\n
> \n
> The usage section is always the second section shown in a help page.\n
>          </usage>\n
> \n
>          <section id="sectionid" title="Generic section"
> short_title= "Generic">\n
> If you need to, you can add additional sections between the usage and
> settings sections.\n
> However, usually, you will not need this while documenting plugins.
> The "id "-attribute\n
> provides an anchor point to jump to this section from the navigation
> menu. The "short_title"\n
> attribute provides a short title to use in the navigation bar. This is
> optional, by default\n
> the main "title" will be used both as a heading to the section, and
> as the link name in the\n
> navigation bar.\n
> \n
> In any section you may want to insert links to further information.
> You do this by adding\n
> \n
> <link href="URL">link name</link>\n
> \n
> Where URL could be an external link such as http://rkward.kde.org .\n
> Several special URLs are supported in the help pages:\n
> \n
> <link href="rkward://page/path/page_id"/>\n
> \n
> This links to a top level rkward help page (not for a plugin).\n
> \n
> <link href="rkward://component/[namespace/]component_id"/>\n
> \n
> This links to the help page of another plugin. The [namespace/] part
> may be omitted\n
> (in this case, rkward is assumed as the standard namespace, e.g.:\n
> <link href="rkward://component/import_spss"/> or\n
> <link href="rkward://component/rkward/import_spss"/> are
> equivalent).\n
> The component_id is the same that you specified in the <link linkend=
> "pluginmap">&pluginmap;</link>.\n
> \n
> <link href="rkward://rhelp/rfunction"/>\n
> \n
> Links to the &r; help page on "rfunction".\n
> \n
> Note that the link names will be generated automatically for these
> types of links.\n
>          </section>\n
> \n
>          <settings>\n
>                  <caption id="id_of_tab_or_frame"/>\n
>                  <setting id="id_of_element">\n
> Description of the GUI element identified by the given id\n
>                  </setting>\n
>                  <setting id="id_of_elementb"
> title="description">\n Usually the title of the GUI element will
> be extracted from the\n <link linkend="mainxml">XML definition of the
> plugin</link>, automatically. However,\n
> for some GUI elements, this description may not be enough to identify
> them, reliably.\n
> In this case, you can add an explicit title using the "title"
> attribute.\n </setting>\n
>                  <setting id="id_of_elementc">\n
> Description of the GUI element identified by "id_of_elementc"\n
>                  </setting>\n
>                  [...]\n
>          </settings>\n
> \n
>          <related>\n
> The related section typically just contains some links, such as:\n
> \n
> <ul>\n
>          <li><link
> href="rkward://rhelp/mean"/></li>\n <li><link
> href="rkward://rhelp/median"/></li>\n <li><link
> href="rkward://component/related_component"/> </li>\n
> </ul>\n
>          </related>\n
> \n
>          <technical>\n
> The technical section (optional, always last) may contain some
> technical details of the plugin\n
> implementation, which are of interest only to RKWard developers. This
> is particularly relevant\n
> for plugins that are designed to be embedded in many other plugins,
> and could detail, which\n
> options are available to customize the embedded plugin, and which code
> sections contain which\n
> R code.\n
>          </technical>\n
> </document>
> 
> =============
> 
> That is all one mesage!
> 
> A message like this one is almost untranslatable (translator getting 
> lost all the time), and  a translator's nightmare, and I strongly
> advise you (or: I beg you) to divide messages like this one into
> smaller chunks.
> 
> Of course a translator can do this him/her self, copying a message
> like that into a wordprocessor, dividing it into translatable chunks,
> and after translating copying them back into the .po file (and
> checking all the line-ends).
> But a translator should be facilitated to do his/her job as
> comfortably as possible, if only to let the translations be as good
> as possible.
> 
> Thanks for reading this, and I hope that you can do something about 
> this, even when a message like this one is included automatically. I
> do not complain only for myself, but also for the tens, or even
> hundreds, of translators all over the world who are confronted with
> messages like this monster.
> 
> Greetings from Holland, sincerely,
> 
> Jaap Woldringh
> Dutch translator for KDE
> 
> 
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://mail.kde.org/pipermail/rkward-devel/attachments/20170127/7728785d/attachment.sig>