contributing: Remove parts of locale readme already present in submit…

…ting guidelines (OSGeo#3012) * Remove parts of locale readme already present in submitting guidelines * Transifex -> Weblate * Reformat to markdown; simplify * Doc: improve wording of gettext examples --------- Co-authored-by: Markus Neteler <[email protected]> Co-authored-by: Markus Neteler <[email protected]> Co-authored-by: Veronica Andreo <[email protected]>
nilason · Nov 7, 2023 · afc4892 · afc4892
1 parent 68884d5
commit afc4892
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 355 deletions.
diff --git a/doc/development/submitting/python.md b/doc/development/submitting/python.md
@@ -301,7 +301,7 @@ output. This is reserved for standard module output if it has one.
 ### Translations
 
 To enable translating of messages to other languages (than English), use full
-strings, e.g.
+strings, e.g. (good example):
 
 ```py
 if ...:
@@ -310,7 +310,7 @@ else:
     win.SetLabel(_("Name for new raster map to create"))
 ```
 
-instead of constructing string from several parts:
+instead of constructing string from several parts (bad example):
 
 ```py
 if ...:

diff --git a/doc/development/submitting/submitting_c.md b/doc/development/submitting/submitting_c.md
@@ -261,32 +261,53 @@ sent to any of these functions will be printed to stderr.
 
 G_message() output is not expected to be sent to pipe or file.
 
-Always use the gettext macros with _("") for user messages, example:
+Messages aiming at the user should be marked for translation. Output meant for
+automatic parsing by other software should not be marked for translation.
+Generally all modules producing output should include localisation header:
+
+```c
+#include "glocale.h"
+```
+
+Afterwards mark all user visible strings with the gettext macro \_("message"):
 
 ```c
 G_fatal_error(_("Vector map <%s> not found"), name);
 ```
 
 It is suggested to add a comment line before translatable user message to give a
 hint to translators about meaning or use of cumbersome or obscure message. First
-word in the comment must be GTC - GRASS translation comment,
+word in the comment must be GTC: GRASS translation comment,
 
 Example:
 
 ```c
-/* GTC A name of a projection */
+/* GTC: Name of a projection */
 G_message(_("State Plane"));
 ```
 
 Any message with a noun in plural form has to pass `n_()` macro, even if for the
-English language it is not required!
+English language is not required! The syntax is
+`n_("English singular", "English plural", count)`
 
 ```c
-G_message(n_("One map", "%d maps", number), number);
+G_message( n_("%d map from mapset <%s> removed",
+              "%d maps from mapset <%s> removed", count), count, mapset);
+/* Notice double use of "count" - as an argument for both functions
+   - n_() and G_message() */
+
+G_message( n_("%d map selected", "%d maps selected", count), count);
+G_message( n_("One file removed", "%d files removed", count) count);
+/* Both of forms of singular case "%d file" or "One file" are correct.
+   The choice between them is purely stylistic one. */
+
+/* Although in English it is not necessary to provide a separate
+   text if "n" always is >1, other languages do have a difference if "n"
+   is i.e. 2-4, or n==10 etc. */
+G_message( n_("Remove map", "Remove maps", count));
+/* Number it self doesn't have to be used in the output text */
 ```
 
-See [locale/README](../../../locale/README) for details.
-
 Pipe/file data output: For data output redirected to pipe or file, please use
 fprintf() and specify the stdout stream as follows: