GNOME.org
 

[gtksourceview] docs: update wrt translatable strings in *.lang files

commit 1c90534cd15140441cd9069d6d14d5d8c0437feb
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Sep 17 15:25:28 2017 +0200

    docs: update wrt translatable strings in *.lang files

 docs/reference/lang-reference.xml.in |   57 +++++++++++++++++++++++----------
 docs/reference/lang-tutorial.xml     |   51 +++++++++++++++---------------
 2 files changed, 65 insertions(+), 43 deletions(-)
---
diff --git a/docs/reference/lang-reference.xml.in b/docs/reference/lang-reference.xml.in
index 0893702..a89bf27 100644
--- a/docs/reference/lang-reference.xml.in
+++ b/docs/reference/lang-reference.xml.in
@@ -162,12 +162,21 @@ underscores ("<code>_</code>").
 </varlistentry>
 
 <varlistentry>
-<term><code>name</code> (mandatory)</term>
-<listitem><para>
-The translatable name of the language presented to the user.
-It can be marked for translation putting an underscore before the attribute
-name (see the gettext documentation).
-</para></listitem>
+<term><code>name</code> or <code>_name</code> (mandatory)</term>
+<listitem>
+  <para>
+    The name of the language presented to the user. With <code>_name</code>, the
+    string is marked for translation (see the gettext documentation).
+  </para>
+
+  <para>
+    The name should be marked for translation only if: (1) it contains a common
+    English word, for example "C++ header" should be translated, but not "C++"
+    or "XML". Or (2) if the name contains several words, because in some
+    languages the word order should be different, for example "LLVM IR" or "RPM
+    spec" should also be marked for translation.
+  </para>
+</listitem>
 </varlistentry>
 
 <varlistentry>
@@ -178,13 +187,13 @@ The version of the XML format (currently "2.0").
 </varlistentry>
 
 <varlistentry>
-<term><code>section</code> (optional)</term>
+<term><code>section</code> or <code>_section</code> (optional)</term>
 <listitem><para>
-The translatable category in which the language has to be grouped when
-presented to the user. It can be marked for translation putting
-an underscore before the attribute name. Currently used categories in
-GtkSourceView are "Source", "Script",  "Markup" and "Other", but
-it is possible to use arbitrary categories (while usually discouraged).
+The category in which the language has to be grouped when presented to the user.
+With <code>_section</code> the string is marked for translation. Currently used
+categories in GtkSourceView are "Source", "Script", "Markup", "Scientific" and
+"Other", but it is possible to use arbitrary categories (while usually
+discouraged). The convention in GtkSourceView is to use <code>_section</code>.
 </para></listitem>
 </varlistentry>
 
@@ -302,11 +311,25 @@ hyphens ("<code>-</code>") and underscores ("<code>_</code>").
 </varlistentry>
 
 <varlistentry>
-<term><code>name</code> (mandatory)</term>
-<listitem><para>
-The user visible translatable name for the style. It has to be preceded
-with a underscore ("<code>_</code>") to be marked for translation.
-</para></listitem>
+<term><code>name</code> or <code>_name</code> (mandatory)</term>
+<listitem>
+  <para>
+    The user visible name for the style. With <code>_name</code> the string is
+    marked for translation.
+  </para>
+
+  <para>
+    The convention in GtkSourceView is to <emphasis>never</emphasis> mark those
+    strings for translation because they are extremely rarely used in the UI of
+    an application (for example it could be used by a GUI tool to edit or create
+    style schemes, but it is not really useful beyond that), and because those
+    strings would be hard to translate (as a result, if those strings are
+    translated, in practice they would often be translated in a way that the
+    user doesn't understand what it means; for example for the C language,
+    "include" or "define" should not be translated, those are keywords of the
+    programming language).
+  </para>
+</listitem>
 </varlistentry>
 
 <varlistentry>
diff --git a/docs/reference/lang-tutorial.xml b/docs/reference/lang-tutorial.xml
index 2c0d35f..7766e27 100644
--- a/docs/reference/lang-tutorial.xml
+++ b/docs/reference/lang-tutorial.xml
@@ -56,21 +56,20 @@ After the usual preamble, the main tag is the <code>&lt;language&gt;</code> elem
 </para>
 
 <programlisting>
-&lt;language id="c" _name="C" version="2.0" _section="Source"&gt;
+&lt;language id="c" name="C" version="2.0" _section="Source"&gt;
 </programlisting>
 
 <para>
 The attribute <code>id</code> is used in external references and defines a standard
 way to refer to this language definition, while the <code>name</code> attribute is
-the name presented to the user (it is translatable using gettext prepending a
-<code>_</code>.)
+the name presented to the user.
 </para>
 
 <para>
-The attribute <code>section</code>, also translatable, tells the category where
-this language should be grouped when it is presented to the user. Currently
-available categories in GtkSourceView are "Source", "Script", "Markup",
-"Scientific" and "Other".
+The attribute <code>section</code> (it is translatable using gettext prepending
+a <code>_</code>), tells the category where this language should be grouped when
+it is presented to the user. Currently available categories in GtkSourceView are
+"Source", "Script", "Markup", "Scientific" and "Other".
 </para>
 
 <para>
@@ -116,14 +115,14 @@ For each style there is a <code>&lt;style&gt;</code> element:
 </para>
 
 <programlisting>
-&lt;style id="comment" _name="Comment" map-to="def:comment"/&gt;
+&lt;style id="comment" name="Comment" map-to="def:comment"/&gt;
 </programlisting>
 
 <para>
 This defines a <code>comment</code> style, which inherits the font
 properties from the defaults style <code>def:comment</code>.
-The <code>name</code> attribute contains the translatable name for this
-style, which is the name to show to the user.
+The <code>name</code> attribute is the name to show to the user (that string
+could for example be used by a GUI tool to edit or create style schemes).
 </para>
 
 <para>
@@ -133,13 +132,13 @@ contexts, so they will share the same appearance.
 </para>
 
 <programlisting>
-&lt;style id="string" _name="String" map-to="def:string"/&gt;
-&lt;style id="escaped-character" _name="Escaped Character" map-to="def:special-char"/&gt;
-&lt;style id="preprocessor" _name="Preprocessor" map-to="def:preprocessor"/&gt;
-&lt;style id="included-file" _name="Included File" map-to="def:string"/&gt;
-&lt;style id="char" _name="Character" map-to="def:character"/&gt;
-&lt;style id="keyword" _name="Keyword" map-to="def:keyword"/&gt;
-&lt;style id="type" _name="Data Type" map-to="def:type"/&gt;
+&lt;style id="string" name="String" map-to="def:string"/&gt;
+&lt;style id="escaped-character" name="Escaped Character" map-to="def:special-char"/&gt;
+&lt;style id="preprocessor" name="Preprocessor" map-to="def:preprocessor"/&gt;
+&lt;style id="included-file" name="Included File" map-to="def:string"/&gt;
+&lt;style id="char" name="Character" map-to="def:character"/&gt;
+&lt;style id="keyword" name="Keyword" map-to="def:keyword"/&gt;
+&lt;style id="type" name="Data Type" map-to="def:type"/&gt;
 </programlisting>
 
 <para>
@@ -607,20 +606,20 @@ for this tutorial:
 
 <programlisting>
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
-&lt;language id="c" _name="C" version="2.0" _section="Source"&gt;
+&lt;language id="c" name="C" version="2.0" _section="Source"&gt;
   &lt;metadata&gt;
     &lt;property name="mimetypes"&gt;text/x-c;text/x-csrc&lt;/property&gt;
     &lt;property name="globs"&gt;*.c&lt;/property&gt;
   &lt;/metadata&gt;
   &lt;styles&gt;
-    &lt;style id="comment" _name="Comment" map-to="def:comment"/&gt;
-    &lt;style id="string" _name="String" map-to="def:string"/&gt;
-    &lt;style id="escaped-character" _name="Escaped Character" map-to="def:special-char"/&gt;
-    &lt;style id="preprocessor" _name="Preprocessor" map-to="def:preprocessor"/&gt;
-    &lt;style id="included-file" _name="Included File" map-to="def:string"/&gt;
-    &lt;style id="char" _name="Character" map-to="def:character"/&gt;
-    &lt;style id="keyword" _name="Keyword" map-to="def:keyword"/&gt;
-    &lt;style id="type" _name="Data Type" map-to="def:type"/&gt;
+    &lt;style id="comment" name="Comment" map-to="def:comment"/&gt;
+    &lt;style id="string" name="String" map-to="def:string"/&gt;
+    &lt;style id="escaped-character" name="Escaped Character" map-to="def:special-char"/&gt;
+    &lt;style id="preprocessor" name="Preprocessor" map-to="def:preprocessor"/&gt;
+    &lt;style id="included-file" name="Included File" map-to="def:string"/&gt;
+    &lt;style id="char" name="Character" map-to="def:character"/&gt;
+    &lt;style id="keyword" name="Keyword" map-to="def:keyword"/&gt;
+    &lt;style id="type" name="Data Type" map-to="def:type"/&gt;
   &lt;/styles&gt;
   &lt;definitions&gt;
     &lt;context id="c"&gt;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]