codekingpro/portable-devtools

1*usr_45.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		     VIM USER MANUAL	by Bram Moolenaar5 6 7			Select your language (locale)8 9 10The messages in Vim can be given in several languages.  This chapter explains11how to change which one is used.  Also, the different ways to work with files12in various languages is explained.13 14|45.1|	Language for Messages15|45.2|	Language for Menus16|45.3|	Using another encoding17|45.4|	Editing files with a different encoding18|45.5|	Entering language text19 20     Next chapter: |usr_50.txt|  Advanced Vim script writing21 Previous chapter: |usr_44.txt|  Your own syntax highlighted22Table of contents: |usr_toc.txt|23 24==============================================================================25*45.1*	Language for Messages26 27When you start Vim, it checks the environment to find out what language you28are using.  Mostly this should work fine, and you get the messages in your29language (if they are available).  To see what the current language is, use30this command: >31 32	:language33 34If it replies with "C", this means the default is being used, which is35English.36 37	Note:38	Using different languages only works when Vim was compiled to handle39	it.  To find out if it works, use the ":version" command and check the40	output for "+gettext" and "+multi_lang".  If they are there, you are41	OK.  If you see "-gettext" or "-multi_lang" you will have to find42	another Vim.43 44What if you would like your messages in a different language?  There are45several ways.  Which one you should use depends on the capabilities of your46system.47   The first way is to set the environment to the desired language before48starting Vim.  Example for Unix: >49 50	env LANG=de_DE.ISO_8859-1  vim51 52This only works if the language is available on your system.  The advantage is53that all the GUI messages and things in libraries will use the right language54as well.  A disadvantage is that you must do this before starting Vim.  If you55want to change language while Vim is running, you can use the second method: >56 57	:language fr_FR.ISO_8859-158 59This way you can try out several names for your language.  You will get an60error message when it's not supported on your system.  You don't get an error61when translated messages are not available.  Vim will silently fall back to62using English.63   To find out which languages are supported on your system, find the64directory where they are listed.  On my system it is "/usr/share/locale".  On65some systems it's in "/usr/lib/locale".  The manual page for "setlocale"66should give you a hint where it is found on your system.67   Be careful to type the name exactly as it should be.  Upper and lowercase68matter, and the '-' and '_' characters are easily confused.69 70You can also set the language separately for messages, edited text and the71time format.  See |:language|.72 73 74DO-IT-YOURSELF MESSAGE TRANSLATION75 76If translated messages are not available for your language, you could write77them yourself.  To do this, get the source code for Vim and the GNU gettext78package.  After unpacking the sources, instructions can be found in the79directory src/po/README.txt.80   It's not too difficult to do the translation.  You don't need to be a81programmer.  You must know both English and the language you are translating82to, of course.83   When you are satisfied with the translation, consider making it available84to others.  Upload it at vim-online (http://vim.sf.net) or e-mail it to85the Vim maintainer <maintainer@vim.org>.  Or both.86 87==============================================================================88*45.2*	Language for Menus89 90The default menus are in English.  To be able to use your local language, they91must be translated.  Normally this is automatically done for you if the92environment is set for your language, just like with messages.  You don't need93to do anything extra for this.  But it only works if translations for the94language are available.95   Suppose you are in Germany, with the language set to German, but prefer to96use "File" instead of "Datei".  You can switch back to using the English menus97this way: >98 99	:set langmenu=none100 101It is also possible to specify a language: >102 103	:set langmenu=nl_NL.ISO_8859-1104 105Like above, differences between "-" and "_" matter.  However, upper/lowercase106differences are ignored here.107   The 'langmenu' option must be set before the menus are loaded.  Once the108menus have been defined changing 'langmenu' has no direct effect.  Therefore,109put the command to set 'langmenu' in your vimrc file.110   If you really want to switch menu language while running Vim, you can do it111this way: >112 113	:source $VIMRUNTIME/delmenu.vim114	:set langmenu=de_DE.ISO_8859-1115	:source $VIMRUNTIME/menu.vim116 117There is one drawback: All menus that you defined yourself will be gone.  You118will need to redefine them as well.119 120 121DO-IT-YOURSELF MENU TRANSLATION122 123To see which menu translations are available, look in this directory:124 125	$VIMRUNTIME/lang ~126 127The files are called menu_{language}.vim.  If you don't see the language you128want to use, you can do your own translations.  The simplest way to do this is129by copying one of the existing language files, and change it.130   First find out the name of your language with the ":language" command.  Use131this name, but with all letters made lowercase.  Then copy the file to your132own runtime directory, as found early in 'runtimepath'.  For example, for Unix133you would do: >134 135	:!cp $VIMRUNTIME/lang/menu_ko_kr.euckr.vim ~/.vim/lang/menu_nl_be.iso_8859-1.vim136 137You will find hints for the translation in "$VIMRUNTIME/lang/README.txt".138 139==============================================================================140*45.3*	Using another encoding141 142Vim guesses that the files you are going to edit are encoded for your143language.  For many European languages this is "latin1".  Then each byte is144one character.  That means there are 256 different characters possible.  For145Asian languages this is not sufficient.  These mostly use a double-byte146encoding, providing for over ten thousand possible characters.  This still147isn't enough when a text is to contain several different languages.  This is148where Unicode comes in.  It was designed to include all characters used in149commonly used languages.  This is the "Super encoding that replaces all150others".  But it isn't used that much yet.151   Fortunately, Vim supports these three kinds of encodings.  And, with some152restrictions, you can use them even when your environment uses another153language than the text.154   Nevertheless, when you only edit files that are in the encoding of your155language, the default should work fine and you don't need to do anything.  The156following is only relevant when you want to edit different languages.157 158 159USING UNICODE IN THE GUI160 161The nice thing about Unicode is that other encodings can be converted to it162and back without losing information.  When you make Vim use Unicode163internally, you will be able to edit files in any encoding.164   Unfortunately, the number of systems supporting Unicode is still limited.165Thus it's unlikely that your language uses it.  You need to tell Vim you want166to use Unicode, and how to handle interfacing with the rest of the system.167   Let's start with the GUI version of Vim, which is able to display Unicode168characters.  This should work: >169 170	:set encoding=utf-8171	:set guifont=-misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1172 173The 'encoding' option tells Vim the encoding of the characters that you use.174This applies to the text in buffers (files you are editing), registers, Vim175script files, etc.  You can regard 'encoding' as the setting for the internals176of Vim.177   This example assumes you have this font on your system.  The name in the178example is for the X Window System.  This font is in a package that is used to179enhance xterm with Unicode support.  If you don't have this font, you might180find it here:181 182	http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz183 184For MS-Windows, some fonts have a limited number of Unicode characters.  Try185using the "Courier New" font.  You can use the Edit/Select Font... menu to186select and try out the fonts available.  Only fixed-width fonts can be used187though.  Example: >188 189	:set guifont=courier_new:h12190 191If it doesn't work well, try getting a fontpack.  If Microsoft didn't move it,192you can find it here:193 194	http://www.microsoft.com/typography/fonts/default.aspx195 196Now you have told Vim to use Unicode internally and display text with a197Unicode font.  Typed characters still arrive in the encoding of your original198language.  This requires converting them to Unicode.  Tell Vim the language199from which to convert with the 'termencoding' option.  You can do it like200this: >201 202	:let &termencoding = &encoding203	:set encoding=utf-8204 205This assigns the old value of 'encoding' to 'termencoding' before setting206'encoding' to utf-8.  You will have to try out if this really works for your207setup.  It should work especially well when using an input method for an Asian208language, and you want to edit Unicode text.209 210 211USING UNICODE IN A UNICODE TERMINAL212 213There are terminals that support Unicode directly.  The standard xterm that214comes with XFree86 is one of them.  Let's use that as an example.215   First of all, the xterm must have been compiled with Unicode support.  See216|UTF8-xterm| how to check that and how to compile it when needed.217   Start the xterm with the "-u8" argument.  You might also need so specify a218font.  Example: >219 220   xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1221 222Now you can run Vim inside this terminal.  Set 'encoding' to "utf-8" as223before.  That's all.224 225 226USING UNICODE IN AN ORDINARY TERMINAL227 228Suppose you want to work with Unicode files, but don't have a terminal with229Unicode support.  You can do this with Vim, although characters that are not230supported by the terminal will not be displayed.  The layout of the text231will be preserved.  >232 233	:let &termencoding = &encoding234	:set encoding=utf-8235 236This is the same as what was used for the GUI.  But it works differently: Vim237will convert the displayed text before sending it to the terminal.  That238avoids that the display is messed up with strange characters.239   For this to work the conversion between 'termencoding' and 'encoding' must240be possible.  Vim will convert from latin1 to Unicode, thus that always works.241For other conversions the |+iconv| feature is required.242   Try editing a file with Unicode characters in it.  You will notice that Vim243will put a question mark (or underscore or some other character) in places244where a character should be that the terminal can't display.  Move the cursor245to a question mark and use this command: >246 247	ga248 249Vim will display a line with the code of the character.  This gives you a hint250about what character it is.  You can look it up in a Unicode table.  You could251actually view a file that way, if you have lots of time at hand.252 253	Note:254	Since 'encoding' is used for all text inside Vim, changing it makes255	all non-ASCII text invalid.  You will notice this when using registers256	and the 'viminfo' file (e.g., a remembered search pattern).  It's257	recommended to set 'encoding' in your vimrc file, and leave it alone.258 259==============================================================================260*45.4*	Editing files with a different encoding261 262Suppose you have setup Vim to use Unicode, and you want to edit a file that is263in 16-bit Unicode.  Sounds simple, right?  Well, Vim actually uses utf-8264encoding internally, thus the 16-bit encoding must be converted, since there265is a difference between the character set (Unicode) and the encoding (utf-8 or26616-bit).267   Vim will try to detect what kind of file you are editing.  It uses the268encoding names in the 'fileencodings' option.  When using Unicode, the default269value is: "ucs-bom,utf-8,latin1".  This means that Vim checks the file to see270if it's one of these encodings:271 272	ucs-bom		File must start with a Byte Order Mark (BOM).  This273			allows detection of 16-bit, 32-bit and utf-8 Unicode274			encodings.275	utf-8		utf-8 Unicode.  This is rejected when a sequence of276			bytes is illegal in utf-8.277	latin1		The good old 8-bit encoding.  Always works.278 279When you start editing that 16-bit Unicode file, and it has a BOM, Vim will280detect this and convert the file to utf-8 when reading it.  The 'fileencoding'281option (without s at the end) is set to the detected value.  In this case it282is "utf-16le".  That means it's Unicode, 16-bit and little-endian.  This283file format is common on MS-Windows (e.g., for registry files).284   When writing the file, Vim will compare 'fileencoding' with 'encoding'.  If285they are different, the text will be converted.286   An empty value for 'fileencoding' means that no conversion is to be done.287Thus the text is assumed to be encoded with 'encoding'.288 289If the default 'fileencodings' value is not good for you, set it to the290encodings you want Vim to try.  Only when a value is found to be invalid will291the next one be used.  Putting "latin1" first doesn't work, because it is292never illegal.  An example, to fall back to Japanese when the file doesn't293have a BOM and isn't utf-8: >294 295	:set fileencodings=ucs-bom,utf-8,sjis296 297See |encoding-values| for suggested values.  Other values may work as well.298This depends on the conversion available.299 300 301FORCING AN ENCODING302 303If the automatic detection doesn't work you must tell Vim what encoding the304file is.  Example: >305 306	:edit ++enc=koi8-r russian.txt307 308The "++enc" part specifies the name of the encoding to be used for this file309only.  Vim will convert the file from the specified encoding, Russian in this310example, to 'encoding'.  'fileencoding' will also be set to the specified311encoding, so that the reverse conversion can be done when writing the file.312   The same argument can be used when writing the file.  This way you can313actually use Vim to convert a file.  Example: >314 315	:write ++enc=utf-8 russian.txt316<317	Note:318	Conversion may result in lost characters.  Conversion from an encoding319	to Unicode and back is mostly free of this problem, unless there are320	illegal characters.  Conversion from Unicode to other encodings often321	loses information when there was more than one language in the file.322 323==============================================================================324*45.5*	Entering language text325 326Computer keyboards don't have much more than a hundred keys.  Some languages327have thousands of characters, Unicode has over hundred thousand.  So how do328you type these characters?329   First of all, when you don't use too many of the special characters, you330can use digraphs.  This was already explained in |24.9|.331   When you use a language that uses many more characters than keys on your332keyboard, you will want to use an Input Method (IM).  This requires learning333the translation from typed keys to resulting character.  When you need an IM334you probably already have one on your system.  It should work with Vim like335with other programs.  For details see |mbyte-XIM| for the X Window system and336|mbyte-IME| for MS-Windows.337 338 339KEYMAPS340 341For some languages the character set is different from latin, but uses a342similar number of characters.  It's possible to map keys to characters.  Vim343uses keymaps for this.344   Suppose you want to type Hebrew.  You can load the keymap like this: >345 346	:set keymap=hebrew347 348Vim will try to find a keymap file for you.  This depends on the value of349'encoding'.  If no matching file was found, you will get an error message.350 351Now you can type Hebrew in Insert mode.  In Normal mode, and when typing a ":"352command, Vim automatically switches to English.  You can use this command to353switch between Hebrew and English: >354 355	CTRL-^356 357This only works in Insert mode and Command-line mode.  In Normal mode it does358something completely different (jumps to alternate file).359   The usage of the keymap is indicated in the mode message, if you have the360'showmode' option set.  In the GUI Vim will indicate the usage of keymaps with361a different cursor color.362   You can also change the usage of the keymap with the 'iminsert' and363'imsearch' options.364 365To see the list of mappings, use this command: >366 367	:lmap368 369To find out which keymap files are available, in the GUI you can use the370Edit/Keymap menu.  Otherwise you can use this command: >371 372	:echo globpath(&rtp, "keymap/*.vim")373 374 375DO-IT-YOURSELF KEYMAPS376 377You can create your own keymap file.  It's not very difficult.  Start with378a keymap file that is similar to the language you want to use.  Copy it to the379"keymap" directory in your runtime directory.  For example, for Unix, you380would use the directory "~/.vim/keymap".381   The name of the keymap file must look like this:382 383	keymap/{name}.vim ~384or385	keymap/{name}_{encoding}.vim ~386 387{name} is the name of the keymap.  Chose a name that is obvious, but different388from existing keymaps (unless you want to replace an existing keymap file).389{name} cannot contain an underscore.  Optionally, add the encoding used after390an underscore.  Examples:391 392	keymap/hebrew.vim ~393	keymap/hebrew_utf-8.vim ~394 395The contents of the file should be self-explanatory.  Look at a few of the396keymaps that are distributed with Vim.  For the details, see |mbyte-keymap|.397 398 399LAST RESORT400 401If all other methods fail, you can enter any character with CTRL-V:402 403	encoding   type			range ~404	8-bit	   CTRL-V 123		decimal 0-255405	8-bit	   CTRL-V x a1		hexadecimal 00-ff406	16-bit     CTRL-V u 013b	hexadecimal 0000-ffff407	31-bit	   CTRL-V U 001303a4	hexadecimal 00000000-7fffffff408 409Don't type the spaces.  See |i_CTRL-V_digit| for the details.410 411==============================================================================412 413Next chapter: |usr_50.txt|  Advanced Vim script writing414 415Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:416