Plugin for XChat

Note: After Apertium's migration to GitHub, this tool is still not under the official Apertium organization. If you are interested in transferring this tool to the organization, see Migrating tools to GitHub.

Description

When this plugin is loaded in XChat, it keeps track of the user's language preferences for different users and channels (both incoming and outgoing messages). If the user has set the language pair eng-spa (English → Spanish) for incoming messages from user1, then the plugin will attempt to tranlate all incoming messages from user1 to Spanish (assuming they will be in English).

There are 3 kinds of language pair bindings:

• user binding. Only available for incoming messages. Binds a language pair to a specific username, so that messages from that user are translated according to the associated pair. This binding ignores channel names, meaning that the translating will be done in every channel a user with the username that was associated with the language pair speaks.

• channel binding. Binds a language pair to a channel, so that all the messages to/from that channel are translated accordingly.

• default binding. If set, the language pair set to default will be user to translate any text that does not fall under any of the previous binding categories.

In case there exist different kinds of bindings that could be used to translate a message, the order of priority (from most to least) is: user, channel, default. This means that if a user who has an associated language pair sends a message in a channel that also has an associated language pair, the message will be translated using the the pair associated to the user. Any users who don't have language pair bindings will have their messages translated using the channel associated language pair.

All bindings are stored to a preferences file and are, therefore, persistent across different XChat sessions.

The translating is done by an Apy that may run locally or on a remote location (its address can be set from within the plugin).

The plugin is able to use several Apy instances, as it stores an ordered Apy list. The first Apy in the list takes priority when the plugin needs to make a request to an Apy. If the first Apy is unreachable or unable to give an answer, the plugin will attempt to make the same request to the second Apy in the list, and so on.

Installing the plugin

Requirements

• Python.
• Apy(Optional). Only needed if you intend to run your own Apy in your machine.

Download and installation

The code can be downloaded here.

Note: After Apertium's migration to GitHub, this tool is still not under the official Apertium organization. If you are interested in transferring this tool to the organization, see Migrating tools to GitHub.

You can get a copy of the code with

git clone https://github.com/Sbalbp/Xchat_Translator_Plugin.git

which will create a local Xchat_Translator_Plugin directory. Now enter this directory and run

./updateSub.sh

This will attempt to retrieve the latest version of the Apertium_Plugin_Utils submodule, a Python module which is necessary for the plugin to work. Since this script always tries to get the latest updates on the submodule, it can be used to keep it up to date.

Now that you have the Python module, you might want to install it. First enter the submodule directory

cd Apertium_Plugin_Utils

and install the module. You can choose between a global installation with

sudo python setup.py install

or you can install the module to a chosen folder (refer to this documentation for different alternatives). In this case you will have to add the path where you installed the module (up to the site-packages folder) to your PYTHONPATH environment variable.

python3 setup.py install --prefix /home/fran/local

Loading the plugin

To load the plugin with XChat go to XChat → Load script or plugin and select the .py file that is included inside the src folder of the Xchat_Translator_Plugin directory. Alternatively, you can also use the /load route command in XChat to load the plugin (for a non-absolute route, XChat current directory is by default home).

Plugin commands

The following commands can be used in XChat when the plugin is loaded:

• /apertium_apy position address Inserts an Apy address at the given position of the Apy list. If no arguments are passed, it just shows the list of addresses. If the address argument is omitted, the address at the given position is shown.

For example, if the Apy list looks like [address1, address2, address3] and we issue the command /apertium_apy 1 http://localhost 2737, it will insert the address http://localhost:2737 to the Apy list in the position number 1, pushing back ay other Apy, which results in the following Apy list: [address1, http://localhost:2737, address2, address3]. This means that the new address wil take priority over address2 and address3 when issuing a command that makes a request to an Apy, but it will always be asked after address1.

The default list only address is http://localhost:2737. The address http://apy.projectjj.com can be added to the list. This address, however, is not guaranteed to work 100% of the times, as it is still in test stage.

• /apertium_removeapy position Removes athe Apy at the given position from the Apy list. If no arguments are passed, all the Apy's are removed.

• /apertium_pairs Asks the first Apy which language pairs are available and shows them.

• /apertium_check user Show the language pair bindings for the given user. If the user argument is omitted, show the default and current channel language pair bindings.

• /apertium_bind direction user source target Sets a language pair for the given user. direction must be either 'incoming' (for incoming messages) or 'outgoing' (for messages sent). source and target are the source and target languages of the language pair to be set, respectively. If no user is provided, the language pair is instead bound to the current channel.

It's worth noting that 'outgoing' messages will only be translated if a language pair has been assigned to either 'default' (with the apertium_default outgoing command) or the channel (for example, the language pair eng-spa to translate your messages in english to spanish in a spanish channel). This means you can't bind an outgoing language pair to a user.

• /apertium_unbind user Unbinds the language pair associated to a user or channel. user (optional) is the name of the user whose associated language pair is to be unbound. If omitted, the language pair is unbound from the channel itself.

• /apertium_default direction source target Sets the language pair to be used to translate messages when there is no language pair for the user that sent the message nor the channel it was sent on. direction must be either 'incoming' (for incoming messages) or 'outgoing' (for messages sent). source and target are the source and target languages of the language pair to be set, respectively.

• /apertium_block user Blocks a given user so that their messages are not translated.

• /apertium_unblock user Unblocks a given blocked user to have their messages translated again.

• /apertium_display displayMode Selects how translated messages are displayed. displayMode must be 'both' (displays the original message and its translation), 'replace' (only displays the translation) or 'compressed' (displays both the original message and its translation in a compressed 2-line way). If no argument is passed, the current display mode is shown.

• /apertium_infodisplay infoDisplayMode Selects how information should be displayed. infoDisplayMode must be 'dialog' (shows a dialog box with the information), 'print' (prints the information in the xchat history) or 'none' (information is not displayed).

Wishlist

• unbind option
• userlist context menu item for translate, e.g. right click on user, ->translate ->from ->to
• different options for translation visualisation
  • replace original text
  • underneath original text
  • tool-tip (ayuda emergente) with either the original or the translation
• make it work with unicode
• allow more than one instance of apy to be specified in an ordered list, and then take union of listPairs, and if more than one server has a given pair, go through in the order of the list
  • e.g. i want to specify localhost + apy.projectjj + apertium-turkic apy.
  • if i have spa-eng on localhost, that should take preference over apy.projectjj.