To create new wiki account, please join us on #znc at freenode and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.

Difference between revisions of "Charset"

From ZNC
Jump to: navigation, search
(Update to latest version provided by archive.org)
(restored from archive.org)
Line 1: Line 1:
ZNC has supported character encodings in core since [[ChangeLog/1.6.0|1.6.0]]. If you want to look at the earlier "charset" module, it's located at [[Charset/old]]. ZNC uses UTF-8 internally. You can configure charset used between ''clients and ZNC'', and charset used between ''ZNC and the IRC server''. Likely values are <code>UTF-8</code> and <code>ISO-8859-1</code>, but you might need other [[wikipedia:Character encoding#Common character encodings|common character encodings]].
+
{{Core Module | version = 1.0}}
  
= Prerequisites =
+
Normalizes (i.e. converts) character encodings.
[http://site.icu-project.org/ ICU library] does the actual conversion. If it's available, <code>./configure</code> will find it.
 
  
= Configure via Web Admin =
+
== Usage ==
[[Image:Charset2.png|frame]][[Image:Charset1.png|frame]]
+
=== Arguments ===
GUI is available in [[webadmin]] on both ''User Settings'' pages (''Client Encoding'', between the user's client and ZNC) and ''Network Settings'' pages (''Server Encoding'', between ZNC and the IRC server).
+
[-force] <client_charset1[,client_charset2[,...]]>  <server_charset1[,server_charset2[,...]]>
  
If one of the "Try to parse as UTF-8 and ___" options is selected, when ZNC receives a line from socket (either client, or server), at first it checks whether it's valid UTF-8, or not. If it's not, the fallback charset is used to decode the line.
+
<code>-force</code> makes the module convert ALL messages instead of probing whether they are already encoded using the target charset (<code>client_charset</code>). This is useful for encodings with byte data that is also valid in the target charset. <code>client_charset2</code> (and so forth, in prioritized order) is the charset used if the message couldn't be encoded to charset1.
  
* After changing the ''Client Encoding'' on the user settings page, the user must reconnect their client to ZNC for settings to take effect.
+
=== Supported charsets ===
* After changing the ''Server Encoding'' on the network settings page, ZNC must be reconnected to the IRC server for settings to take effect, for example by typing <code>/msg *status Connect</code>.
+
All charsets supported by iconv are also supported by the module. At least in theory. Use <code>iconv --list</code> on your shell to get a list.
  
<div style="clear:both"></div>
+
=== Examples ===
 +
If your client understands and/or receives UTF-8 only, but some weird server you are on wants ISO-8859-1 exclusively:
 +
/znc loadmod charset UTF-8 ISO-8859-1
  
= Configure via Control Panel module =
+
If people on that server confuse basic charsets:
Make sure the [[controlpanel]] module is enabled. The following commands are available:
+
/znc loadmod charset UTF-8 ISO-8859-1,ISO-8859-15,WINDOWS-1252
:<code>/msg *controlpanel Set ClientEncoding <user> <value></code>
+
This will make ZNC send ISO-8859-1 to the server, but convert ISO-8859-1, ISO-8859-15 and WINDOWS-1252 to UTF-8 in the other direction.
:<code>/msg *controlpanel SetNetwork Encoding <user> <network> <value></code>
 
  
The <code><value></code> comes in 4 flavors, which map to 4 options in webadmin:
+
If your client sends ISO-8859-1 but you want UTF-8 to be sent to your channels:
* <code></code> (empty): Don't ensure any encoding at all (legacy mode, not recommended)
+
/znc loadmod charset ISO-8859-1 UTF-8
* <code>^foo</code>: Try to parse as UTF-8 and as <code>foo</code>, send as UTF-8 (recommended)
+
You should also use this one if your clients sends ISO-8859-1 and you heavily use webadmin. Webadmin only displays UTF-8 (weird characters appear for other encodings).
* <code>*foo</code>: Try to parse as UTF-8 and as <code>foo</code>, send as <code>foo</code>
 
* <code>foo</code>: Parse and send as <code>foo</code> only.
 
If one of the "Try to parse as UTF-8 and ___" options is used (by prepending '''^''' or '''*''' to the value), when ZNC receives a line from socket (either client, or server), at first it checks whether it's valid UTF-8, or not. If it's not, the fallback charset is used to decode the line.
 
  
==Examples==
+
If your client only speaks UTF-8, but the server wants CP1251 exclusively:
; To set the encoding between user ''Kathryn'''s client and ZNC to "''Try to parse as UTF-8 and as <code>ISO-8859-15</code>, send as UTF-8 (recommended)''," you would use:
+
/znc loadmod charset -force UTF-8 CP1251
: <code>/msg *controlpanel Set ClientEncoding Kathryn ^ISO-8859-15</code>
 
: …and then user ''Kathryn'' would have to reconnect her client to ZNC.
 
  
; To set user ''Kathryn'''s encoding between ZNC and the IRC network named ''freenodeIRC'' to "''Try to parse as UTF-8 and as <code>UTF-8</code>, send as UTF-8 (recommended)''," you would use:
+
== Warning ==
: <code>/msg *controlpanel SetNetwork Encoding Kathryn freenodeIRC ^UTF-8</code>
+
If you connect multiple clients, and send a message from client A, client B will receive the ''converted'' version of the message. This is just how ZNC works and cannot be changed by a module.
: …and then ZNC would have to reconnect to network ''freenodeIRC'', for example by typing <code>/msg *status Connect</code>
 

Revision as of 21:29, 3 April 2017


Normalizes (i.e. converts) character encodings.

Usage

Arguments

[-force] <client_charset1[,client_charset2[,...]]>  <server_charset1[,server_charset2[,...]]>

-force makes the module convert ALL messages instead of probing whether they are already encoded using the target charset (client_charset). This is useful for encodings with byte data that is also valid in the target charset. client_charset2 (and so forth, in prioritized order) is the charset used if the message couldn't be encoded to charset1.

Supported charsets

All charsets supported by iconv are also supported by the module. At least in theory. Use iconv --list on your shell to get a list.

Examples

If your client understands and/or receives UTF-8 only, but some weird server you are on wants ISO-8859-1 exclusively:

/znc loadmod charset UTF-8 ISO-8859-1

If people on that server confuse basic charsets:

/znc loadmod charset UTF-8 ISO-8859-1,ISO-8859-15,WINDOWS-1252

This will make ZNC send ISO-8859-1 to the server, but convert ISO-8859-1, ISO-8859-15 and WINDOWS-1252 to UTF-8 in the other direction.

If your client sends ISO-8859-1 but you want UTF-8 to be sent to your channels:

/znc loadmod charset ISO-8859-1 UTF-8

You should also use this one if your clients sends ISO-8859-1 and you heavily use webadmin. Webadmin only displays UTF-8 (weird characters appear for other encodings).

If your client only speaks UTF-8, but the server wants CP1251 exclusively:

/znc loadmod charset -force UTF-8 CP1251

Warning

If you connect multiple clients, and send a message from client A, client B will receive the converted version of the message. This is just how ZNC works and cannot be changed by a module.