From: Bruno Haible <bruno@clisp.org>
Date: Fri, 8 Sep 2006 16:37:12 +0000 (+0000)
Subject: Discourage unusual markup in translatable strings.
X-Git-Tag: 0.16.x-branchpoint~162
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c05cb5286c7bb11585decda7c34e7f00e5df5399;p=thirdparty%2Fgettext.git

Discourage unusual markup in translatable strings.
---

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 0fb4c3e5a..411e2ffb1 100644
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,8 @@
+2006-09-08  Bruno Haible  <bruno@clisp.org>
+
+	* gettext.texi (Preparing strings): Also discourage unusual markup.
+	Suggested by Paul Eggert.
+
 2006-08-28  Bruno Haible  <bruno@clisp.org>
 
 	* gettext.texi (aclocal): Update file list.
diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 7662a400f..f8249624b 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -1630,6 +1630,9 @@ Split at paragraphs.
 
 @item
 Use format strings instead of string concatenation.
+
+@item
+Avoid unusual markup and unusual control characters.
 @end itemize
 
 @noindent
@@ -1849,6 +1852,32 @@ Console.WriteLine(
     String.Format("Replace @{0@} with @{1@}?", object1, object2));
 @end example
 
+@cindex markup
+@cindex control characters
+Unusual markup or control characters should not be used in translatable
+strings.  Translators will likely not understand the particular meaning
+of the markup or control characters.
+
+For example, if you have a convention that @samp{|} delimits the
+left-hand and right-hand part of some GUI elements, translators will
+often not understand it without specific comments.  It might be
+better to have the translator translate the left-hand and right-hand
+part separately.
+
+Another example is the @samp{argp} convention to use a single @samp{\v}
+(vertical tab) control character to delimit two sections inside a
+string.  This is flawed.  Some translators may convert it to a simple
+newline, some to blank lines.  With some PO file editors it may not be
+easy to even enter a vertical tab control character.  So, you cannot
+be sure that the translation will contain a @samp{\v} character, at the
+corresponding position.  The solution is, again, to let the translator
+translate two separate strings and combine at run-time the two translated
+strings with the @samp{\v} required by the convention.
+
+HTML markup, however, is common enough that it's probably ok to use in
+translatable strings.  But please bear in mind that the GNU gettext tools
+don't verify that the translations are well-formed HTML.
+
 @node Mark Keywords, Marking, Preparing Strings, Sources
 @section How Marks Appear in Sources
 @cindex marking strings that require translation