vim-patch:8.2.1544: cannot translate messages in a Vim script

Problem:    Cannot translate messages in a Vim script.
Solution:   Add gettext().  Try it out for a few messages in the options
            window.

0b39c3fd4c

Co-authored-by: Bram Moolenaar <Bram@vim.org>

runtime/doc/builtin.txt

@@ -220,6 +220,7 @@ gettabvar({nr}, {varname} [, {def}])
 gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
 				any	{name} in {winnr} in tab page {tabnr}
 gettagstack([{nr}])		Dict	get the tag stack of window {nr}
+gettext({text})			String	lookup translation of {text}
 getwininfo([{winid}])		List	list of info about each window
 getwinpos([{timeout}])		List	X and Y coord in pixels of the Vim window
 getwinposx()			Number	X coord in pixels of Vim window
@@ -3584,6 +3585,19 @@ gettagstack([{winnr}])					*gettagstack()*
 		Can also be used as a |method|: >
 			GetWinnr()->gettagstack()
 
+
+gettext({text})						*gettext()*
+		Translate {text} if possible.
+		This is mainly for use in the distributed Vim scripts.  When
+		generating message translations the {text} is extracted by
+		xgettext, the translator can add the translated message in the
+		.po file and Vim will lookup the translation when gettext() is
+		called.
+		For {text} double quoted strings are preferred, because
+		xgettext does not understand escaping in single quoted
+		strings.
+
+
 getwininfo([{winid}])					*getwininfo()*
 		Returns information about windows as a |List| with Dictionaries.
 

runtime/doc/usr_41.txt

@@ -639,6 +639,7 @@ String manipulation:					*string-functions*
 	execute()		execute an Ex command and get the output
 	win_execute()		like execute() but in a specified window
 	trim()			trim characters from a string
+	gettext()		lookup message translation
 
 List manipulation:					*list-functions*
 	get()			get an item without error for wrong index

runtime/optwin.vim

@@ -149,13 +149,13 @@ exe $OPTWIN_CMD . ' new option-window'
 setlocal ts=15 tw=0 noro buftype=nofile
 
 " Insert help and a "set" command for each option.
-call append(0, '" Each "set" line shows the current value of an option (on the left).')
-call append(1, '" Hit <CR> on a "set" line to execute it.')
-call append(2, '"            A boolean option will be toggled.')
-call append(3, '"            For other options you can edit the value before hitting <CR>.')
-call append(4, '" Hit <CR> on a help line to open a help window on this option.')
-call append(5, '" Hit <CR> on an index line to jump there.')
-call append(6, '" Hit <Space> on a "set" line to refresh it.')
+call append(0, gettext('" Each "set" line shows the current value of an option (on the left).'))
+call append(1, gettext('" Hit <Enter> on a "set" line to execute it.'))
+call append(2, gettext('"            A boolean option will be toggled.'))
+call append(3, gettext('"            For other options you can edit the value before hitting <Enter>.'))
+call append(4, gettext('" Hit <Enter> on a help line to open a help window on this option.'))
+call append(5, gettext('" Hit <Enter> on an index line to jump there.'))
+call append(6, gettext('" Hit <Space> on a "set" line to refresh it.'))
 
 " These functions are called often below.  Keep them fast!
 

src/nvim/eval.lua

@@ -185,6 +185,7 @@ return {
     gettabvar={args={2, 3}, base=1},
     gettabwinvar={args={3, 4}, base=1},
     gettagstack={args={0, 1}, base=1},
+    gettext={args=1, base=1},
     getwininfo={args={0, 1}, base=1},
     getwinpos={args={0, 1}, base=1},
     getwinposx={},

src/nvim/eval/funcs.c

@@ -3502,6 +3502,19 @@ static void f_glob2regpat(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
   rettv->vval.v_string = (pat == NULL) ? NULL : file_pat_to_reg_pat(pat, NULL, NULL, false);
 }
 
+/// "gettext()" function
+static void f_gettext(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
+{
+  if (argvars[0].v_type != VAR_STRING
+      || argvars[0].vval.v_string == NULL
+      || *argvars[0].vval.v_string == NUL) {
+    semsg(_(e_invarg2), tv_get_string(&argvars[0]));
+  } else {
+    rettv->v_type = VAR_STRING;
+    rettv->vval.v_string = xstrdup(_(argvars[0].vval.v_string));
+  }
+}
+
 /// "has()" function
 static void f_has(typval_T *argvars, typval_T *rettv, EvalFuncData fptr)
 {

src/nvim/po/fixfilenames.vim

@@ -0,0 +1,13 @@
+" Invoked with the name "vim.pot" and a list of Vim script names.
+" Converts them to a .js file, stripping comments, so that xgettext works.
+
+set shortmess+=A
+
+for name in argv()[1:]
+  let jsname = fnamemodify(name, ":t:r") .. ".js"
+  exe "%s+" .. jsname .. "+" .. name .. "+"
+endfor
+
+write
+last
+quit

src/nvim/po/tojavascript.vim

@@ -0,0 +1,18 @@
+" Invoked with the name "vim.pot" and a list of Vim script names.
+" Converts them to a .js file, stripping comments, so that xgettext works.
+" Javascript is used because, like Vim, it accepts both single and double
+" quoted strings.
+
+set shortmess+=A
+
+for name in argv()[1:]
+  exe 'edit ' .. fnameescape(name)
+
+  " Strip comments
+  g/^\s*"/s/.*//
+
+  " Write as .js file, xgettext recognizes them
+  exe 'w! ' .. fnamemodify(name, ":t:r") .. ".js"
+endfor
+
+quit