[education/rkward] doc/rkwardplugins: Clarify role of po_id in pluginsmaps. Remove some obsolete info.
Thomas Friedrichsmeier
null at kde.org
Sat Sep 26 12:00:19 BST 2020
Git commit 268b13b02aa4454905aeb5feadddb6e4b9008e7e by Thomas Friedrichsmeier.
Committed on 26/09/2020 at 10:59.
Pushed by tfry into branch 'master'.
Clarify role of po_id in pluginsmaps. Remove some obsolete info.
M +8 -42 doc/rkwardplugins/index.docbook
https://invent.kde.org/education/rkward/commit/268b13b02aa4454905aeb5feadddb6e4b9008e7e
diff --git a/doc/rkwardplugins/index.docbook b/doc/rkwardplugins/index.docbook
index 3b6f7364..22e62387 100644
--- a/doc/rkwardplugins/index.docbook
+++ b/doc/rkwardplugins/index.docbook
@@ -52,7 +52,7 @@ as Authors, publish date, the abstract, and Keywords -->
and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
-<date>2020-05-11</date>
+<date>2020-09-26</date>
<releaseinfo>0.7.2</releaseinfo>
<abstract>
@@ -1989,9 +1989,9 @@ x </components ...>
<para>
For &rkward;'s &XML; files, i18n will mostly just work. If you are writing your own <command>.pluginmap</command> (⪚ for an <link linkend="external_plugins">external plugin</link>),
you will have to specify a <replaceable>po_id</replaceable> next to the pluginmap's <replaceable>id</replaceable>. This defines the "message catalog" to use. In general this should
- be set identical to the <replaceable>id</replaceable> of your <command>.pluginmap</command>, but if you provide several <command>.pluginmap</command>s and want to control, how
- message catalogs are divided up, this allows you to do so. The <replaceable>po_id</replaceable> is inherited by any <command>.pluginmap</command> you include, unless that declares
- a different <replaceable>po_id</replaceable>, and by all plugins declared in it.
+ be set identical to the <replaceable>id</replaceable> of your <command>.pluginmap</command>, but if you provide several related <command>.pluginmap</command>s in a single package, you will
+ probaly want to specify a common <replaceable>po_id</replaceable> in your maps. The <replaceable>po_id</replaceable> of a <command>.pluginmap</command> file is inherited by all plugins
+ declared in it, unless unless that declares a different <replaceable>po_id</replaceable>.
</para>
<para>
For plugins and help pages, you do not need to tell &rkward; which strings are to be translated, because that is generally evident from their usage. However, as explained above,
@@ -2107,46 +2107,15 @@ user (selection from a list of values shown next to this element) -->
E.g. if an unsuspecting translator translates a string meant as a variable name in two distinct words with a space in between.
</para>
</sect2>
-
- <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 do not 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, ⪚ 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>
<sect1 id="i18n_workflow"><title>Translation maintainance</title>
<para>
Now that you have made your plugin translatable, how do you actually get it translated? In general you only need to worry about this, when developing an <link linkend="external_plugins">
- external plugin</link>. For plugins in &rkward;'s main repository, all the magic is done for you. Here is the basic workflow. Note that you need the "gettext" tools, installed:
+ external plugin</link>. For plugins in &rkward;'s main repository, all the magic is done for you. Here is the basic workflow for a external plugins. Note that you need the "gettext" tools, installed:
</para>
<itemizedlist>
<listitem><para>Mark up all strings, providing context and comments as needed</para></listitem>
- <listitem><para>Run <command>python scripts/update_plugin_messages.py --extract-only /path/to/my.pluginmap</command>. scripts/update_plugin_messages.py is not currently part of the source
+ <listitem><para>Run <command>python3 scripts/update_plugin_messages.py --extract-only /path/to/my.pluginmap</command>. scripts/update_plugin_messages.py is not currently part of the source
releases, but can be found in a source repository checkout.</para></listitem>
<listitem><para>Distribute the resulting <command>rkward__<replaceable>POID</replaceable>.pot</command> file to your translators. For external plugins, it is recommended to place it
in a subfolder "po" in inst/rkward.</para></listitem>
@@ -2155,13 +2124,13 @@ user (selection from a list of values shown next to this element) -->
<listitem><para>Translator saves the translation as <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command> (where
<replaceable>xx</replaceable> is the language code), and sends it back to you.</para></listitem>
<listitem><para>Copy <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command> to your sources, next to
- <command>rkward__<replaceable>POID</replaceable>.pot</command>. Run <command>python scripts/update_plugin_messages.py /path/to/my.pluginmap</command> (Note: without
+ <command>rkward__<replaceable>POID</replaceable>.pot</command>. Run <command>python3 scripts/update_plugin_messages.py /path/to/my.pluginmap</command> (Note: without
<replaceable>--extract-only</replaceable>, this time). This will merge the translation with any interim string changes, compile the translation, and install it into
<command><replaceable>DIR_OF_PLUGINMAP</replaceable>/po/<replaceable>xx</replaceable>/LC_MESSAGES/rkward__<replaceable>POID</replaceable>.mo</command> (where
<replaceable>xx</replaceable> is the language code, again).</para></listitem>
<listitem><para>You should also include the non-compiled translation (&ie; <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/update_plugin_messages.py /path/to/my.pluginmap</command> to update the .pot file, but also the
+ <listitem><para>For any update of your plugin, run <command>python3 scripts/update_plugin_messages.py /path/to/my.pluginmap</command> to update the .pot file, but also the
existing .po-files, and the compiled message catalogs.</para></listitem>
</itemizedlist>
</sect1>
@@ -2178,9 +2147,6 @@ user (selection from a list of values shown next to this element) -->
be to leave the term untranslated, or to include the English term in parentheses. Do not 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 rkward-devel mailing list, or to ask for up-to-date instructions,
- there.</para></listitem>
</itemizedlist>
</sect1>
</chapter>
More information about the kde-doc-english
mailing list