From 5a6618cc57097e1e7205ad6b1d967a3ad79d016e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nathana=C3=ABl=20Courant?=
 <Ekdohibs@users.noreply.github.com>
Date: Sat, 26 Aug 2017 09:43:08 +0200
Subject: [PATCH] Add '@n' escape sequences and some documentation on
 translated strings.

---
 builtin/common/misc_helpers.lua |  2 ++
 doc/lua_api.txt                 | 10 ++++++++++
 src/translation.cpp             |  4 ++++
 3 files changed, 16 insertions(+)

diff --git a/builtin/common/misc_helpers.lua b/builtin/common/misc_helpers.lua
index 67eda11f3..5fc589b72 100644
--- a/builtin/common/misc_helpers.lua
+++ b/builtin/common/misc_helpers.lua
@@ -704,6 +704,8 @@ function core.translate(textdomain, str, ...)
 			end
 			arg_index = arg_index + 1
 			return ESCAPE_CHAR .. "F" .. arg[a] .. ESCAPE_CHAR .. "E"
+		elseif matched == "n" then
+			return "\n"
 		else
 			return matched
 		end
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 6ff9c9433..152da5985 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2199,6 +2199,15 @@ Two functions are provided to translate strings: `minetest.translate` and `minet
 
   this will be displayed as "Laine Rouge" on clients with a French locale.
 
+### Operations on translated strings
+
+The output of `minetest.translate` is a string, with escape sequences adding additional information to that string
+so that it can be translated on the different clients. In particular, you can't expect operations like string.length
+to work on them like you would expect them to, or string.gsub to work in the expected manner. However, string
+concatenation will still work as expected (note that you should only use this for things like formspecs; do not
+translate sentences by breaking them into parts; arguments should be used instead), and operations such as
+`minetest.colorize` which are only concatenation under the hood as well.
+
 ### Translation file format
 A translation file has the suffix `.[lang].tr`, where `[lang]` is the language it corresponds to.
 The file should be a text file, with the following format:
@@ -2221,6 +2230,7 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
   files to avoid begin confused with the `=` separating the original from the translation.
 * `@\n` (where the `\n` is a literal newline) acts as a literal newline. As with `@=`, this escape is not required
   in strings given to `minetest.translate`, but is in translation files.
+* `@n` acts as a literal newline as well.
 
 `minetest` namespace reference
 ------------------------------
diff --git a/src/translation.cpp b/src/translation.cpp
index e8582f328..31efca41e 100644
--- a/src/translation.cpp
+++ b/src/translation.cpp
@@ -80,6 +80,8 @@ void Translations::loadTranslation(const std::string &data)
 				if (i + 1 < wline.length()) {
 					if (wline[i + 1] == L'=') {
 						word1.put(L'=');
+					} else if (wline[i + 1] == L'n') {
+						word1.put(L'\n');
 					} else {
 						word1.put(L'@');
 						word1.put(wline[i + 1]);
@@ -113,6 +115,8 @@ void Translations::loadTranslation(const std::string &data)
 				if (i + 1 < wline.length()) {
 					if (wline[i + 1] == L'=') {
 						word2.put(L'=');
+					} else if (wline[i + 1] == L'n') {
+						word2.put(L'\n');
 					} else {
 						word2.put(L'@');
 						word2.put(wline[i + 1]);