summaryrefslogtreecommitdiffstats
path: root/runtime/doc/mlang.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/mlang.txt')
-rw-r--r--runtime/doc/mlang.txt222
1 files changed, 222 insertions, 0 deletions
diff --git a/runtime/doc/mlang.txt b/runtime/doc/mlang.txt
new file mode 100644
index 0000000..8997e1c
--- /dev/null
+++ b/runtime/doc/mlang.txt
@@ -0,0 +1,222 @@
+*mlang.txt* For Vim version 9.0. Last change: 2022 Sep 17
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Multi-language features *multilang* *multi-lang*
+
+This is about using messages and menus in various languages. For editing
+multibyte text see |multibyte|.
+
+The basics are explained in the user manual: |usr_45.txt|.
+
+1. Messages |multilang-messages|
+2. Menus |multilang-menus|
+3. Scripts |multilang-scripts|
+
+Also see |help-translated| for multi-language help.
+
+{not available when compiled without the |+multi_lang| feature}
+
+==============================================================================
+1. Messages *multilang-messages*
+
+Vim picks up the locale from the environment. In most cases this means Vim
+will use the language that you prefer, unless it's not available.
+
+To see a list of supported locale names on your system, look in one of these
+directories (for Unix):
+ /usr/lib/locale ~
+ /usr/share/locale ~
+Unfortunately, upper/lowercase differences matter. Also watch out for the
+use of "-" and "_".
+
+ *:lan* *:lang* *:language* *E197*
+:lan[guage]
+:lan[guage] mes[sages]
+:lan[guage] cty[pe]
+:lan[guage] tim[e]
+:lan[guage] col[late]
+ Print the current language (aka locale).
+ With the "messages" argument the language used for
+ messages is printed. Technical: LC_MESSAGES.
+ With the "ctype" argument the language used for
+ character encoding is printed. Technical: LC_CTYPE.
+ With the "time" argument the language used for
+ strftime() is printed. Technical: LC_TIME.
+ With the "collate" argument the language used for
+ collation order is printed. Technical: LC_COLLATE.
+ Without argument all parts of the locale are printed
+ (this is system dependent).
+ The current language can also be obtained with the
+ |v:lang|, |v:ctype|, |v:collate| and |v:lc_time|
+ variables.
+
+:lan[guage] {name}
+:lan[guage] mes[sages] {name}
+:lan[guage] cty[pe] {name}
+:lan[guage] tim[e] {name}
+:lan[guage] col[late] {name}
+ Set the current language (aka locale) to {name}.
+ The locale {name} must be a valid locale on your
+ system. Some systems accept aliases like "en" or
+ "en_US", but some only accept the full specification
+ like "en_US.ISO_8859-1". On Unix systems you can use
+ this command to see what locales are supported: >
+ :!locale -a
+< With the "messages" argument the language used for
+ messages is set. This can be different when you want,
+ for example, English messages while editing Japanese
+ text. This sets $LC_MESSAGES.
+ With the "ctype" argument the language used for
+ character encoding is set. This affects the libraries
+ that Vim was linked with. It's unusual to set this to
+ a different value from 'encoding' or "C". This sets
+ $LC_CTYPE.
+ With the "time" argument the language used for time
+ and date messages is set. This affects strftime().
+ This sets $LC_TIME.
+ With the "collate" argument the language used for the
+ collation order is set. This affects sorting of
+ characters. This sets $LC_COLLATE.
+ Without an argument all are set, and additionally
+ $LANG is set.
+ If available the LC_NUMERIC value will always be set
+ to "C", so that floating point numbers use '.' as the
+ decimal point.
+ This will make a difference for items that depend on
+ the language (some messages, time and date format).
+ Not fully supported on all systems
+ If this fails there will be an error message. If it
+ succeeds there is no message. Example: >
+ :language
+ Current language: C
+ :language de_DE.ISO_8859-1
+ :language mes
+ Current messages language: de_DE.ISO_8859-1
+ :lang mes en
+<
+
+MS-WINDOWS MESSAGE TRANSLATIONS *win32-gettext*
+
+If you used the self-installing .exe file, message translations should work
+already. Otherwise get the libintl.dll file if you don't have it yet:
+
+ http://sourceforge.net/projects/gettext
+Or:
+ https://mlocati.github.io/gettext-iconv-windows/
+
+This also contains tools xgettext, msgformat and others.
+
+libintl.dll should be placed in same directory as (g)vim.exe, or one of the
+directories listed in the PATH environment value. Vim also looks for the
+alternate names "libintl-8.dll" and "intl.dll".
+
+Message files (vim.mo) have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES",
+where "xx" is the abbreviation of the language (mostly two letters).
+
+If you write your own translations you need to generate the .po file and
+convert it to a .mo file. You need to get the source distribution and read
+the file "src/po/README.txt".
+
+To overrule the automatic choice of the language, set the $LANG variable to
+the language of your choice. use "en" to disable translations. >
+
+ :let $LANG = 'ja'
+
+(text for Windows by Muraoka Taro)
+
+==============================================================================
+2. Menus *multilang-menus*
+
+See |45.2| for the basics, esp. using 'langmenu'.
+
+Note that if changes have been made to the menus after the translation was
+done, some of the menus may be shown in English. Please try contacting the
+maintainer of the translation and ask him to update it. You can find the
+name and e-mail address of the translator in
+"$VIMRUNTIME/lang/menu_<lang>.vim".
+
+To set the font (or fontset) to use for the menus, use the |:highlight|
+command. Example: >
+
+ :highlight Menu font=k12,r12
+
+
+ALIAS LOCALE NAMES
+
+Unfortunately, the locale names are different on various systems, even though
+they are for the same language and encoding. If you do not get the menu
+translations you expected, check the output of this command: >
+
+ echo v:lang
+
+Now check the "$VIMRUNTIME/lang" directory for menu translation files that use
+a similar language. A difference in a "-" being a "_" already causes a file
+not to be found! Another common difference to watch out for is "iso8859-1"
+versus "iso_8859-1". Fortunately Vim makes all names lowercase, thus you
+don't have to worry about case differences. Spaces are changed to
+underscores, to avoid having to escape them.
+
+If you find a menu translation file for your language with a different name,
+create a file in your own runtime directory to load that one. The name of
+that file could be: >
+
+ ~/.vim/lang/menu_<v:lang>.vim
+
+Check the 'runtimepath' option for directories which are searched. In that
+file put a command to load the menu file with the other name: >
+
+ runtime lang/menu_<other_lang>.vim
+
+
+TRANSLATING MENUS
+
+If you want to do your own translations, you can use the |:menutrans| command,
+explained below. It is recommended to put the translations for one language
+in a Vim script. For a language that has no translation yet, please consider
+becoming the maintainer and make your translations available to all Vim users.
+Send an e-mail to the Vim maintainer <maintainer@vim.org>.
+
+ *:menut* *:menutrans* *:menutranslate*
+:menut[ranslate] clear
+ Clear all menu translations.
+
+:menut[ranslate] {english} {mylang}
+ Translate menu name {english} to {mylang}. All
+ special characters like "&" and "<Tab>" need to be
+ included. Spaces and dots need to be escaped with a
+ backslash, just like in other |:menu| commands.
+ Case in {english} is ignored.
+
+See the $VIMRUNTIME/lang directory for examples.
+
+To try out your translations you first have to remove all menus. This is how
+you can do it without restarting Vim: >
+ :source $VIMRUNTIME/delmenu.vim
+ :source <your-new-menu-file>
+ :source $VIMRUNTIME/menu.vim
+
+Each part of a menu path is translated separately. The result is that when
+"Help" is translated to "Hilfe" and "Overview" to "Überblick" then
+"Help.Overview" will be translated to "Hilfe.Überblick".
+
+==============================================================================
+3. Scripts *multilang-scripts*
+
+In Vim scripts you can use the |v:lang| variable to get the current language
+(locale). The default value is "C" or comes from the $LANG environment
+variable.
+
+The following example shows how this variable is used in a simple way, to make
+a message adapt to language preferences of the user, >
+
+ :if v:lang =~ "de_DE"
+ : echo "Guten Morgen"
+ :else
+ : echo "Good morning"
+ :endif
+<
+
+ vim:tw=78:sw=4:ts=8:noet:ft=help:norl: