Deploying to gh-pages from @ e51b0e8 🚀

Author: MichaelChirico

articles/custom-diagnostic.html

@@ -75,7 +75,8 @@ message("This", " is", " a", " message")
 warning("This", " is", " a", " warning")
 #> Warning: This is a warning
 stop("This", " is", " an", " error")
-#> Error: This is an error
+#> Error:
+#> ! This is an error
 ```
 
 However, as you’ll learn shortly, this style is unlikely to generate
@@ -148,6 +149,50 @@ 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[²](#fn2) 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)
+#> [1] "Running job in parallel."
+```
+
+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.")
+}
+#> [1] "Running job in parallel."
+```
+
+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.
+
 ### Write full sentences
 
 Generally, you should strive to make sure that each message comes from a

articles/developers.html

@@ -5,7 +5,7 @@ articles:
   custom-diagnostic: custom-diagnostic.html
   developers: developers.html
   translators: translators.html
-last_built: 2025-12-20T06:04Z
+last_built: 2025-12-26T20:39Z
 urls:
   reference: https://michaelchirico.github.io/potools/reference
   article: https://michaelchirico.github.io/potools/articles

articles/developers.md

@@ -278,8 +278,8 @@ print(metadata)
 #> msgstr ""
 #> "Project-Id-Version: potoolsExample 0.0.1\n"
 #> "Report-Msgid-Bugs-To: https://github.com/ruser/potoolsExample/issues\n"
-#> "POT-Creation-Date: 2025-12-20 06:04+0000\n"
-#> "PO-Revision-Date: 2025-12-20 06:04+0000\n"
+#> "POT-Creation-Date: 2025-12-26 20:39+0000\n"
+#> "PO-Revision-Date: 2025-12-26 20:39+0000\n"
 #> "Last-Translator: R User <ruser@gmail.com>\n"
 #> "Language-Team: ar_SY\n"
 #> "Language: ar_SY\n"
@@ -298,8 +298,8 @@ writeLines(readLines(tmp_po))
 #> msgstr ""
 #> "Project-Id-Version: potoolsExample 0.0.1\n"
 #> "Report-Msgid-Bugs-To: https://github.com/ruser/potoolsExample/issues\n"
-#> "POT-Creation-Date: 2025-12-20 06:04+0000\n"
-#> "PO-Revision-Date: 2025-12-20 06:04+0000\n"
+#> "POT-Creation-Date: 2025-12-26 20:39+0000\n"
+#> "PO-Revision-Date: 2025-12-26 20:39+0000\n"
 #> "Last-Translator: R User <ruser@gmail.com>\n"
 #> "Language-Team: ar_SY\n"
 #> "Language: ar_SY\n"
@@ -327,7 +327,7 @@ writeLines(readLines(tmp_pot))
 #> msgstr ""
 #> "Project-Id-Version: potoolsExample 0.0.1\n"
 #> "Report-Msgid-Bugs-To: https://github.com/ruser/potoolsExample/issues\n"
-#> "POT-Creation-Date: 2025-12-20 06:04+0000\n"
+#> "POT-Creation-Date: 2025-12-26 20:39+0000\n"
 #> "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 #> "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 #> "Language-Team: LANGUAGE <LL@li.org>\n"