From Apertium
Jump to navigation Jump to search

Apertium-viewer is a tool to view and edit the output of the various stages of an apertium translation.

The various stages update while you type, and a change made in any one pane updates the subsequent stages.

A screen shot. Some stages are hidden (split panes have been moved together)

Such a tool is invaluable when you want to work with a language pair.

Installing and running apertium-viewer

Make sure you have Java installed

Download apertium-viewer.jar and save it to your hard drive.

Double-click on apertium-viewer.jar (or right click on it and open with Java Runtime)

If this doesent work for you, try typing from the command line:

wget https://svn.code.sf.net/p/apertium/svn/builds/apertium-viewer/apertium-viewer.jar
java -jar apertium-viewer.jar 

Testing unreleased language pairs from subversion

At startup Apertium-viewer will scan for languages installed on the system, but you really need to install your own language pairs anywhere to use it. Just compile the language pair with 'make' and point to the .mode file generated: Choose File | Load mode and select the mode file from the language pair.

Opening a mode file

The online language pairs are also supported. You can choose any of the 24 online pairs that are available and work with them as if they where installed locally, even if they aren't.

Keyboard shortcuts

  • Alt-U: Set/unset 'mark unknown words'
  • Alt-I: Fit text: Automatically resising panes. Stages with unchanged text are automatically collapsed.
  • Alt-C: Copy All: Puts text for all stages into clipboard
  • Alt-S: Hide/Show commands (for clearer view)
  • Ctrl-0/Ctrl-1 brings focus to the first pane (input),
  • Ctrl-2 brings focus to the to the second pane (etc).
  • Ctrl-9 brings focus to the last pane (output). It autoscrolls to make the panes fully visible.
  • Ctrl-Pgup, Ctrl-PgDn: Cycle throgh the text panes
  • Ctrl-Z/Ctrl-Y Undo/redo on a per text-pane/stage basis
  • Ctrl-T: Make test case: Text can be copied directly into a Regression testing wiki page (also using Tools | Make Test Case...).
  • Ctrl-I: Import Wiki text case


  • Syntax highlighting. If a surface form has an ambigious analysis its shown in red. If you click on an alternative it is selected (basically, between / /) and can be removed it pressing Delete key.
A click on an ambigious analysis selects one posibility (press Del to delete it). Also the freeze button is shown.
  • Views can be frozen/paused to not propagate changes
  • Zoom button to get a detached window (particularly input and output windows).
When the text is the same as on the former stage it is shown with a yellow background. Commands have been hidden for a clearer view. Coloring scheme for version 1.4 is shown
  • Language pairs can be tested directly from the SVN source directory, without installing them ('make install'). Unlike [Apertium-view], it doesent use dbus. Rather you can just directly point to a mode file and use it.
  • Online language pairs can be used within the application without the need of having them locally.

Version 1.3 (dec 2008)

Apertium-viewer showing a Wiki Regression testing case text ready to be pasted.
Apertium-viewer import of a Wiki Regression testing case.
  • Up to 10 texts can be stored for later use
  • Text field with keyboard focus is highlighted

Version 1.4 (apr 2010)

  • Much improved highlighting: Different colors for ambigious and unrecognized words, and for chunks
  • A "Hide intermediate" button hides all but input and output text

Version 1.5 (nov 2010)

  • Option to ignore error messages from commands (stderr) to make it usable for Gramtrans stuff

Version 2.0 (aug 2012)

  • Completely based on lttoolbox-java. This removes the requirement of a local Apertium installation, and offers a much higher translation speed. External processing can still be enabled in the options.
  • Support for the 25 online language pairs. All these pairs can be used within the application without the need of having them locally.
  • Full and meaningful names for the modes (for instance, "Basque → Spanish" instead of "eu-es").

Version 2.1 (april 2015)

  • More robust and user friendly startup and UI
  • Automatically store separate input text for each source language
  • One big JAR file (easyer than the dist/lib/ folder). Java Web start is dropped as it wont work with self-signed certificates.

Version 2.2 (april 2015)

  • Commands are highlighted for better readability
  • If you switch to a new language, a bundled example phrase is shown

For developers

  • Click on a command to edit the source code!
  • Validate XML dictionary and transfer files!
  • After a change you can recompile the pair and immediately see the result!


  • Create a dedicated lexer (see http://jflex.de/) for our dictionary format
  • Polish the editor, create better autocompletion
  • Integrate tools from apertium-dixtools

See development in https://sourceforge.net/p/apertium/svn/60272/log/?path=/trunk/apertium-viewer

Feature requests/bugs

  • Restoring of view sizes after restart is not perfect (press Fit to text to fix)
  • Shrinking view sizes not perfect (press Fit to text a few times to fix)
  • The scrollbar on the right doesn't appear until you press "Fit".
  • Re-use the processes instead of respawning (use null-flush)
  • Use apertium-transfer with the -t option, catching and parsing stderr so that rule numbers can be displayed.
  • Make it a development platform: Let user easily view/edit the concerned dictionaries and issue 'make' for him.

Getting, compiling and running apertium-viewer from source

Check out the source code (Netbeans project) from the subversion repository.

svn co https://svn.code.sf.net/p/apertium/svn/trunk/apertium-viewer
cd apertium-viewer
ant run

To run it's easiest just to type 'ant run' or use Netbeans to compile. You might need to specify where to look for JDK, like:

ant -Dplatforms.default_platform.home=/usr run


Troubleshooting if it won't start

If the wiewer wont start up and you get something like this in the console

Unregognized parameter: ?
LTProc3.2j: process a stream with a letter transducer
USAGE: LTProc [-c] [-a|-g|-n|-d|-b|-p|-s|-t] fst_file [input_file [output_file]]

then it means that you've hit an internal bug that prevents the viewer from starting: The viewer is internally using lttoolbox-java for processing (when the viewer starts, it will try to use lttoolbox-java on the last used language pair, but if that pair is using an option unkown to lttoolbox-java, then the program will EXIT, making you unable to switch to another mode!).

The solution A) either is to delete a preferences file that apertium-viewer uses to remember the last used pair. On Linux the file to delete would be:


B) remove the problematic .mode. You can do that by uninstalling language pairs and/or doing 'make clean' in your SVN pairs.

OSX troubleshooting

Delete the preferences file:


If this still doesn't work try recompiling the program from source (run, ant run) --Jonasfromseier 17:09, 6 May 2013 (UTC)

Mac users

Many modern macs come with an old JDK 1.5. Make sure JDK 1.6 is installed and paste

/System/Library/Frameworks/JavaVM.framework/Versions/1.6/Commands/java -jar apertium-viewer.jar 

into the terminal

Related software

  • Apertium-view is a simpler version of the same program and coded in Python instead of Java and dequires dbus and that you install your language pairs.
  • Apertium-view.sh is a short shell script that just displays output from all parts of the pipeline, no interactive features
  • Apertium-tolk is similar to, but much simpler than Apertium-viewer. It only has an input window and an output window. Where Apertium-viewer is aimed at developers, Apertium-tolk is intended to be as user friendly as possible.