Exemplify fragmented sentences (#332)

Author: MichaelChirico

vignettes/developers.Rmd

@@ -117,6 +117,33 @@ In part, this is an extension of writing messages that are easy to understand in
 And if it's hard for a native English speaker to understand your message, it's going to be even harder once it's translated into another language.
 The following sections give some advice about how to write good messages, as inspired by the "[Preparing translatable strings](https://www.gnu.org/software/gettext/manual/html_node/Preparing-Strings.html#Preparing-Strings%20(Inspired%20by%20from%20))" section of the gettext[^2] manual.
 
+One important point is to avoid templating out sentence fragments, especially words. Put message pieces into a template if and only if they are untranslatable (e.g., proper nouns, function names/R code).
+
+For example, it is bad practice to conditionally template a word or phrase into a message:
+
+```{r}
+# BAD
+in_parallel <- TRUE
+run_type <- if (in_parallel) "in parallel" else "sequentially"
+sprintf(tr_("Running job %s."), run_type)
+```
+
+The translator only sees `"Running job %s."`, and cannot adapt the translation for the two cases. It's much better to use two different, complete messages:
+
+```{r}
+# GOOD
+in_parallel <- TRUE
+if (in_parallel) {
+  tr_("Running job in parallel.")
+} else {
+  tr_("Running job sequentially.")
+}
+```
+
+This gives the translator full context. Why is this important? Because different words can require entirely different sentence structures in other languages. For example, in Polish, "to run [a job] sequentially" can be expressed with a specific verb, `szeregować`. A natural translation of "Running job sequentially." might be "Szeregowanie zadania.". For "Running job in parallel.", one would likely use a different verb and structure, like "Uruchamianie zadania równolegle.".
+
+The template in the "BAD" example is too rigid. It forces the translator to find a single translation for "Running job %s." that works with both "sequentially" and "in parallel", which is unnatural and may not even be possible. The "GOOD" example, by providing two distinct sentences, allows the translator to pick the most idiomatic phrasing for each case.
+
 [^2]: gettext is the underlying library that powers R's translation system.
 
 ### Write full sentences