InstallingAndRunning.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"../../../docbook-xml-4.5/docbookx.dtd">
<chapter id="chapter.installing.and.running">
  <title>Installing and running <application>OmegaT</application></title>

  <section>
    <title id="Windows.users">Windows Users<indexterm class="singular">
        <primary>Installing OmegaT</primary>

        <secondary>Windows</secondary>
      </indexterm></title>

    <section>
      <title id="which.package.to.download.windows">Downloading the
      package</title>

      <para>Do you have a Java implementation compatible with Oracle's Java
      1.6 JRE?</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Yes: </emphasis>download
          <emphasis>OmegaT_3.n.n_Windows_without_JRE.exe</emphasis>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">No / I don't know:</emphasis>
          download<emphasis> OmegaT_3.n.n_Windows.exe.</emphasis></para>

          <para>This package is bundled with Oracle's Java Runtime
          Environment. This JRE will not interfere with other Java
          implementations that may already be installed on your system.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="OmegaT.installation.Windows">
      <title><application>Installing OmegaT</application></title>

      <para>To install <application>OmegaT</application>, double-click on the
      program you have downloaded.</para>

      <para>At the beginning of the installation you can select the language
      to be used during the installation. In the following window you can
      indicate that the language selected is to be used in OmegaT. If you
      check the corresponding checkbox, the OmegaT.l4J.ini file is modified to
      use the language selected (see next section for details). Later, after
      you have accepted the license agreement, the setup program asks you
      whether you wish to create a folder in the <emphasis>start</emphasis>
      menu, and whether you wish to create a shortcut on the desktop and in
      the quick launch bar - you can create these shortcuts later by dragging
      <emphasis><application>OmegaT</application>.exe</emphasis> to the
      desktop or to the start menu to link it from there. The last frame
      offers you to have a look at the readme and changes files for the
      version you have installed.</para>
    </section>

    <section id="running.OmegaT.Windows">
      <title>Running <application>OmegaT<indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>Windows</secondary>
        </indexterm></application></title>

      <para>Once <application>OmegaT</application> is installed, you can click
      on <emphasis><application>OmegaT</application>.jar</emphasis> to launch
      it directly or you can launch it directly from the command line.</para>

      <para>The simplest way to launch OmegaT, however, is to execute
      the<emphasis> <application>OmegaT</application>.exe</emphasis> program.
      <indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>Windows</secondary>

          <tertiary>INI file</tertiary>
        </indexterm>The options for the program start-up in this case will be
      read from the <emphasis><application>OmegaT</application>.l4J.ini
      </emphasis>file, which resides in the same folder as the exe file and
      which you can edit to reflect your setup. The following example for the
      INI file reserves 1GB of memory, requests French as the user language
      and Canada as the country:</para>

      <literallayout><code># OmegaT.exe runtime configuration
# To use a parameter, remove the '#' before the '-'
# Memory 
-Xmx1024M 
# Language 
-Duser.language=FR
# Country 
-Duser.country=CA </code></literallayout>

      <para>Advice: if OmegaT works slowly in Remote Desktop sessions under
      Windows, you may use this option:</para>

      <literallayout><code>-Dsun.java2d.noddraw=false</code></literallayout>
    </section>

    <section>
      <title>Upgrading OmegaT <indexterm class="singular">
          <primary>Upgrading OmegaT</primary>

          <secondary>Windows</secondary>
        </indexterm></title>

      <para><emphasis>This information applies only to the "Traditional"
      Windows versions of OmegaT. It does not apply to the Web Start versions,
      which are upgraded automatically, nor to cross-platform versions
      installed on Windows.</emphasis></para>

      <para>If you already have a version of OmegaT installed on your PC and
      wish to upgrade to a more recent version, you have two options:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Install over the existing installation.
          </emphasis>To do this, simply select the same installation folder as
          the existing installation when installing the new version. The "old"
          version of OmegaT will be overwritten, but any settings from it will
          be retained. This includes preferences set from within OmegaT, any
          changes you have made to your<filename> OmegaT.l4J.ini</filename>
          file, and also your launch script (.bat file), if you are using
          one.</para>
        </listitem>
      </itemizedlist>

      <para>With this method, you may also download the "Windows without JRE"
      version, since the new installation will use your existing JRE.</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Install to a new folder. </emphasis>This
          will enable you to keep both versions side-by-side, which you may
          wish to do until you feel comfortable with the new version. This
          method will also use preferences and settings you have made from
          within OmegaT. In this case, however:</para>

          <itemizedlist>
            <listitem>
              <para>If you have made changes to your<filename> OmegaT.l4J.ini
              </filename>file and/or are using a .bat file, you must copy
              these over.</para>
            </listitem>
          </itemizedlist>

          <itemizedlist>
            <listitem>
              <para>If your existing OmegaT installation is a "Windows with
              JRE" version, the new version must also be a "Windows with JRE"
              version.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section id="Linux.Intel.users">
    <title>Linux (Intel) Users<indexterm class="singular">
        <primary>Installing OmegaT</primary>

        <secondary>Linux</secondary>
      </indexterm></title>

    <section id="which.package.to.download.Linux">
      <title>Downloading the right package</title>

      <para>Do you have a Java implementation compatible with Oracle's Java
      1.6 JRE?</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Yes: </emphasis>download
          <emphasis>OmegaT_3.n.n_Without_JRE.zip</emphasis>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">No / I don't know:</emphasis> download
          <emphasis>OmegaT_3.n.n_Linux.tar.bz2.</emphasis></para>

          <para>This package is bundled with Oracle's Java Runtime
          Environment. This JRE will not interfere with other Java
          implementations that may already be installed on your system.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="OmegaT.installation.Linux">
      <title><application>Installing OmegaT</application></title>

      <para>Unpack/untar the downloaded file. This will create an omegat/
      folder in the working folder in which you will find all the files needed
      to run <application>OmegaT</application>. To untar the
      <emphasis>.tar.gz</emphasis> file:</para>

      <para><emphasis>$ tar xf downloaded_file.tar.gz</emphasis></para>
    </section>

    <section id="adding.OmegaT.to.your.menus.or.panels">
      <title>Adding <application>OmegaT</application> to your menus (KDE) or
      panels (Gnome)</title>

      <section id="KDE.users">
        <title>KDE 4 Users<indexterm class="singular">
            <primary>Customizing OmegaT</primary>

            <secondary>Linux</secondary>
          </indexterm></title>

        <para>You can add <application>OmegaT</application> to your menus as
        follows:</para>

        <itemizedlist>
          <listitem>
            <para>Press <emphasis role="bold"> <keysym>Alt+F2</keysym>
            </emphasis> to show KRunner. Type
            <emphasis>kmenuedit+enter</emphasis> to run the command. The
            KMenuEditor appears. In KMenuEditor select <emphasis>File -&gt;
            New Item.</emphasis></para>
          </listitem>

          <listitem>
            <para>Then, after selecting a suitable menu, add a submenu/item
            with <emphasis>File - New</emphasis> Submenu and <emphasis>File -
            New Item</emphasis>. Enter <application>OmegaT</application> as
            the name of the new item.</para>
          </listitem>

          <listitem>
            <para>In the "Command" field, use the navigation button to find
            your <application>OmegaT</application> launch script (the file
            named <application>OmegaT</application> in the unpacked folder),
            and select it.</para>
          </listitem>

          <listitem>
            <para>Click on the icon button (to the right of the
            Name/Description/Comment fields)</para>
          </listitem>

          <listitem>
            <para>Other Icons - Browse, and navigate to the /images subfolder
            in the <application>OmegaT</application> application folder.
            Select the <application>OmegaT</application>.png icon.</para>
          </listitem>

          <listitem>
            <para>Finally, save the changes with <emphasis>File -
            Save.</emphasis></para>
          </listitem>
        </itemizedlist>
      </section>

      <section id="GNOME.users">
        <title>GNOME Users</title>

        <para>You can add <application>OmegaT</application> to your menus as
        follows:</para>

        <itemizedlist>
          <listitem>
            <para>Right-click on the panel - <emphasis>Add New
            Launcher.</emphasis></para>
          </listitem>

          <listitem>
            <para>Enter "<application>OmegaT</application>" in the "Name"
            field; in the "Command" field, use the navigation button to find
            your <application>OmegaT</application> launch script (the file
            named <application>OmegaT</application> in the unpacked folder).
            Select it and confirm with OK.</para>
          </listitem>

          <listitem>
            <para>Click on the icon button, then hit
            <emphasis>Browse...</emphasis> and navigate to the /images
            subfolder in the <application>OmegaT</application> application
            folder. Select the
            <emphasis><application>OmegaT</application>.png</emphasis> icon.
            GNOME may fail to display the icon files in the available formats
            and initially appear to expect an SVG file, but if the folder is
            selected, the files should appear and
            <application>OmegaT</application>.png can be selected.</para>
          </listitem>
        </itemizedlist>
      </section>
    </section>

    <section id="running.OmegaT.Linux">
      <title>Running <application>OmegaT<indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>Linux</secondary>
        </indexterm></application></title>

      <para>You can launch OmegaT from the command line with a script that
      includes start-up options or you can click on
      <emphasis><application>OmegaT</application>.jar</emphasis> to launch it
      directly. Methods differ depending on the distribution. Make sure that
      your <emphasis>PATH </emphasis>settings are correct and that
      .<emphasis>jar</emphasis> files are properly associated with a Java
      launcher. Check "Command line launching" below for more
      information.</para>
    </section>
  </section>

  <section id="MAC.OSX.users">
    <title>Mac OS X Users<indexterm class="singular">
        <primary>Installing OmegaT</primary>

        <secondary>OS X</secondary>
      </indexterm></title>

    <section id="which.package.to.download.OSX">
      <title>Downloading the package</title>

      <para><application>OmegaT</application> contains the Java JRE 1.7</para>

      <para>Download <emphasis>OmegaT_3.n.n_Mac.zip.</emphasis></para>
    </section>

    <section id="OmegaT.installation.OSX">
      <title><application>Installing OmegaT </application></title>

      <para>Double click on <emphasis>OmegaT_3.n.n_Mac.zip</emphasis> to
      unpack it. This creates a folder called <emphasis>
      <application>OmegaT</application> </emphasis>. The folder contains 2
      files: index.html and
      <emphasis><application>OmegaT</application>.app.</emphasis> Copy the
      folder to a suitable folder (e.g. Applications). Once you have done
      this, you can delete the <emphasis>OmegaT_3.n.n_Mac.zip</emphasis> file,
      it is no longer needed.</para>
    </section>

    <section id="adding.OmegaT.to.the.dock">
      <title>Adding <application>OmegaT</application> to the Dock</title>

      <para>Drag and drop
      <emphasis><application>OmegaT</application>.app</emphasis> onto the
      Dock.</para>
    </section>

    <section id="running.OmegaT.OSX">
      <title>Running <application>OmegaT<indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>OS X</secondary>
        </indexterm></application></title>

      <para>Double-click on<emphasis>
      <application>OmegaT</application>.app</emphasis> or click on its
      location in the Dock.</para>

      <para>You can modify OmegaT's behaviour by editing the
      <emphasis>Properties</emphasis> as well as the
      <emphasis>OmegaT.sh</emphasis> file in the package.</para>

      <para>To access
      <application><emphasis>OmegaT.sh</emphasis></application>, right-click
      on <emphasis><application>OmegaT</application>.app</emphasis> and select
      "Show Package Contents", then open the file in Contents/MacOS by
      right-clicking on it and selecting your text editor of choice. You can
      also "cd" there directly from the command line and open
      <application><emphasis>OmegaT.sh</emphasis> in a command line editor
      like emacs or vi</application>.<indexterm class="singular">
          <primary>Customizing OmegaT</primary>

          <secondary>OS X</secondary>

          <tertiary>Launch parameters</tertiary>
        </indexterm></para>

      <para>Options are changed by modifying <emphasis>OmegaT.sh</emphasis>.
      For pre-defined options, remove the # before a parameter to enable it.
      For example, <filename>LANGUAGE="-Duser.language=ja"</filename> (without
      the #) will launch <application>OmegaT</application> with the user
      interface in Japanese.</para>

      <para>To change the amount of memory available, edit directly the
      lauching line. For instance, <filename>${JAVA} -Xmx2048m ${MACOS}
      ${LANGUAGE} ${COUNTRY} ${PROXY_HOST} ${PROXY_PORT} ${GOOGLE_API_KEY}
      ${MS_CLIENT_ID} ${MS_CLIENT_SECRET} ${MY_MEMORY_EMAIL} ${TAAS_USER_KEY}
      -jar OmegaT.jar</filename> will launch OmegaT with 2 gigas of
      memory.</para>

      <para>To launch multiple instances of
      <emphasis><application>OmegaT</application>.app</emphasis>, double-click
      the file <emphasis>OmegaT.sh</emphasis> located in
      <emphasis><application>OmegaT</application>.app/
      Contents/MacOS/</emphasis>.</para>

      <para>Use the <emphasis><application>OmegaT</application>.jar</emphasis>
      file located in
      <emphasis><application>OmegaT</application>.app/Contents/MacOS/Java/</emphasis>
      to launch <application>OmegaT</application> from the command line. Check
      "Command line launching" below for more information.</para>
    </section>

    <section id="Mac.OSX.goodies">
      <title>Mac OS X goodies</title>

      <para><emphasis><application>OmegaT</application>.app</emphasis> can be
      accessed from the Mac OS X Services. You can thus select a word anywhere
      in <application>OmegaT</application> and use Services to check this
      word, for instance in Spotlight or in Google. You can also use
      AppleScript or Automator to create Services or scripts that will
      automate frequent actions</para>
    </section>
  </section>

  <section id="other.systems">
    <title>Other Systems<indexterm class="singular">
        <primary>Installing OmegaT</primary>

        <secondary>Other systems</secondary>
      </indexterm></title>

    <para>This information applies to systems such as Solaris SPARC/x86/x64,
    Linux x64/PowerPC, Windows x64</para>

    <section>
      <title id="which.package.to.download.other">Downloading the right
      package</title>

      <para><application>OmegaT</application> is available bundled with a
      Oracle Java JRE for Linux (Intel x86) and Windows platforms. Users of
      other platforms (Linux PowerPC, Linux x64, Solaris SPARC/x86/x64,
      Windows x64 etc) must have a running compatible Java JRE on their system
      to be able to use <application>OmegaT</application>.</para>

      <para>Do you have a Java implementation compatible with Oracle's Java
      1.6 JRE?</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Yes: </emphasis>download
          <emphasis>OmegaT_3.n.n_Windows_without_JRE.</emphasis>zip. This
          package can be used on any platform where a Java 1.6 JRE compatible
          JRE is installed.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">I don't know:</emphasis> open a terminal
          and type "java -version". If a "command not found" or similar
          message is returned, it is likely that Java is not installed on your
          system</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">No:</emphasis> obtain a Java JRE for
          your system (see below) and download
          <emphasis>OmegaT_3.n.n_Without_JRE.zip</emphasis>.</para>

          <para>Oracle provides JREs for Solaris SPARC/x86 (Java 1.6) and for
          Linux x64, Solaris x64, Windows x64 (Java 1.6) at <ulink
          url="http://www.oracle.com/technetwork/java/archive-139210.html">http://www.oracle.com/technetwork/java/archive-139210.html</ulink></para>

          <para>IBM provides JREs for Linux PowerPC at <ulink
          url="http://www.ibm.com/developerworks/java/jdk/linux/download.html">http://www.ibm.com/developerworks/java/jdk/linux/download.htm</ulink></para>

          <para>Follow the installation instructions of the package you
          need.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="OmegaT.installation.other">
      <title><application>Installing OmegaT</application><indexterm
          class="singular">
          <primary>Installing OmegaT</primary>

          <secondary>Other systems</secondary>
        </indexterm></title>

      <para>To install <application>OmegaT</application>, simply unpack the
      <emphasis role="bold">OmegaT_3.n.n_Without_JRE.zip</emphasis> file. This
      creates an <emphasis>./OmegaT_3.n.n_Without_JRE/</emphasis> folder in
      the working folder with all the files necessary to run
      <application>OmegaT</application>.</para>
    </section>

    <section id="installing.convenient.shortcuts">
      <title>Installing convenient shortcuts</title>

      <para>Follow your system's instructions to install
      <application>OmegaT</application> shortcuts in convenient places of your
      choosing.</para>
    </section>

    <section id="running.OmegaT.other">
      <title>Running <application>OmegaT<indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>Other systems</secondary>
        </indexterm></application></title>

      <para>Once <application>OmegaT</application> is installed, you can
      launch it directly from the command line, you can create a script that
      includes launch parameters for the command line or you can click on
      <emphasis><application>OmegaT</application>.jar</emphasis> to launch it
      directly. Methods differ depending on the distribution. Make sure that
      your <emphasis>PATH</emphasis> settings are correct and that
      <emphasis>.jar </emphasis> files are properly associated with a Java
      launcher. Check "Command line launching" below for more
      information.</para>
    </section>
  </section>

  <section id="using.Java.Web.Start">
    <title>Using Java Web Start<indexterm class="singular">
        <primary>Running OmegaT</primary>

        <secondary>Using Java Web Start</secondary>
      </indexterm></title>

    <para>Java Web Start technology (part of Java 1.6 and above) can be used
    to deploy standalone Java software applications with a single click over
    the network. Java Web Start ensures that the latest version of the
    application will be deployed, as well as the correct version of the Java
    Runtime Environment (JRE) used. To start OmegaT for the first time with
    Java Web Start, load the following URL in your browser:</para>

    <para><emphasis>http://omegat.sourceforge.net/webstart/<application>OmegaT</application>.jnlp</emphasis></para>

    <para>Download the file<emphasis>
    <application>OmegaT</application>.jnlp</emphasis> and then click on it.
    During the installation, depending on your operating system, you may
    receive several security warnings. The permissions you give to this
    version (which may appear as "unrestricted access to the computer") are
    identical to the permissions you give to the local version, i.e., they
    allow access to the hard drive of the computer. Subsequent clicks on
    <emphasis><application>OmegaT</application>.jnlp</emphasis> will check for
    any upgrades, install them, if there are any, and then start
    <application>OmegaT</application>. After the initial installation you can,
    of course, also use
    <emphasis><application>OmegaT</application>.jnlp</emphasis> also when you
    are offline.</para>

    <para><emphasis role="bold">Privacy</emphasis>:
    <application>OmegaT</application> Java Web Start does not save any of your
    information beyond the computer on which you are running it. The
    application runs on your machine only. Your documents and translation
    memories remain on your computer, and the
    <application>OmegaT</application> project will have no access to your work
    or information.</para>

    <para>Note that if you need or wish to use any of the launch command
    arguments (see above), you must use the normal installation.</para>
  </section>

  <section>
    <title>Starting OmegaT from the command line<indexterm class="singular">
        <primary>Running OmegaT</primary>

        <secondary>Command line launching</secondary>
      </indexterm></title>

    <para>Normally, it is not necessary to start
    <application>OmegaT</application> from the command line. However, the
    command-line alternative allows the user to control and modify the
    program's behavior. There are two ways of launching
    <application>OmegaT</application> using the command line.</para>

    <section id="method1.opening.commandline.window">
      <title>Opening a command line window</title>

      <para>A command line window is also referred to as a "terminal window".
      On Windows it is called an "MS-DOS window" and is available from the
      Start Menu, inside Programs, through the "MS-DOS" item. The Mac OS X
      equivalent is the application Terminal located in Applications →
      Utilities.</para>

      <para>To launch <application>OmegaT</application>, you must normally
      type two commands. The first of these is:</para>

      <para><emphasis> <literal>cd {folder}</literal> </emphasis></para>

      <para>where<emphasis> {folder}</emphasis> is the name of the folder,
      with complete path, in which your <application>OmegaT</application>
      program - specifically, the file
      <emphasis><application>OmegaT</application>.jar</emphasis> - is located.
      In practice, this command will therefore be something like this:</para>

      <para>On Windows</para>

      <para><emphasis> <literal>cd C:\Program
      Files\<application>OmegaT</application></literal> </emphasis></para>

      <para>On Mac OS X</para>

      <para><literal> <literal>cd &lt;<application>OmegaT</application>.app
      location&gt;/<application>OmegaT</application>.app/Contents/Resources/Java/</literal>
      </literal></para>

      <para>On Linux</para>

      <para><literal>cd /usr/local/omegat</literal></para>

      <para>This command changes the folder to the folder containing the
      executable <application>OmegaT</application> file. The second command is
      the command which actually launches <application>OmegaT</application>.
      In its most basic form, this command is:</para>

      <para><literal>java -jar
      <application>OmegaT</application>.jar</literal></para>

      <para>Pay attention to the capitalization - in OS other than Windows,
      the program will not start, if you enter <emphasis>omegat</emphasis>
      instead of <emphasis>OmegaT </emphasis>!</para>

      <para>This method has a particular benefit of being suitable for finding
      causes of problems: if an error occurs during use of the program, an
      error message is output in the terminal window which may contain useful
      information on the cause of the error.</para>

      <para>The above method somewhat impractical way of launching a program
      routinely. For this reason, the two commands described above are
      contained in a file (a "script", also called a ".bat file" on Windows
      systems).</para>

      <para>When this file is executed, the commands within it are
      automatically carried out. Consequently, to make changes to the launch
      command, it is sufficient to modify the file.</para>
    </section>

    <section id="launch.command.arguments">
      <title>Launch command arguments<indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>Launch script arguments</secondary>
        </indexterm></title>

      <para>The basic command has already been mentioned above. Changes to
      this command involve the addition of "arguments" to it. Arguments are
      added after the initial <emphasis>"java"</emphasis>, and before the
      <emphasis>"-jar <application>OmegaT</application>.jar"</emphasis>. Note
      that in Windows you can change the
      <filename>OmegaT.l4J.ini</filename> file to
      reflect your preferences. In other platforms, you can modify your 
      launcher (e.g., <filename>OmegaT.sh</filename> on the Mac, 
      <filename>OmegaT</filename> under Linux) to do the same.</para>

      <para>A list of possible arguments is given below. Advanced users can
      obtain more information on the arguments by typing <emphasis>man
      java</emphasis> in the terminal window.</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">User interface language
          </emphasis></para>

          <para><emphasis role="bold">-Duser.language=XX</emphasis><indexterm
              class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>User interface language</tertiary>
            </indexterm> Normally, i.e. when <application>OmegaT</application>
          is launched without any arguments, the program first detects the
          language of the user's operating system. If a user interface in this
          language is available, <application>OmegaT</application> uses it.
          So, if the user's operating system is Russian and
          <application>OmegaT</application> has been localized in Russian,
          <application>OmegaT</application> is displayed with a Russian user
          interface, Russian menus, etc. If the language of the user's system
          is not available, <application>OmegaT</application> defaults to
          English. This is the standard behavior.</para>

          <para>The <emphasis>"-Duser.language=XX"</emphasis> argument causes
          <application>OmegaT</application> to use the language specified
          rather than the language of the user's operating system. "XX" in the
          command stands for the two-digit code of the desired language. To
          launch <application>OmegaT</application> with a French interface
          (for example on a Russian operating system), the command would
          therefore be:</para>

          <para><literal>java -Duser.language=fr -jar
          <application>OmegaT</application>.jar</literal></para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">User country</emphasis></para>

          <para><emphasis role="bold">-Duser.country=XX</emphasis><indexterm
              class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>User country</tertiary>
            </indexterm> Besides the language, you can also specify the
          country, for example CN or TW in case of the Chinese language. To
          display the instant start guide in the desired language, you need to
          specify both the language and the country. This is necessary even if
          there's only one combination available, like pt_BR in case of
          Portuguese / Brazil.</para>
        </listitem>
      </itemizedlist>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Memory assignment</emphasis></para>

          <para><emphasis role="bold">-XmxZZM </emphasis><indexterm
              class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>Memory assignment</tertiary>
            </indexterm>This command assigns more memory to
          <application>OmegaT</application>. By default, 512 MB are assigned,
          so there is no advantage in assigning less than this figure. "ZZ"
          stands for the amount of memory assigned, in megabytes. The command
          to launch <application>OmegaT</application> with assignment of 1024
          MB (1 gigabyte) of memory is therefore:</para>

          <para><literal>java -Xmx1024M -jar
          <application>OmegaT</application>.jar</literal></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Proxy host IP address</emphasis></para>

          <para><emphasis role="bold"><emphasis
          role="bold">-Dhttp.proxyHost=nnn.nnn.nnn.nnn</emphasis> <indexterm
              class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>Proxy host IP address</tertiary>
            </indexterm></emphasis> The IP address of your proxy server, if
          your system uses a proxy.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Proxy host port number</emphasis></para>

          <para><emphasis role="bold">-Dhttp.proxyPort=NNNN</emphasis>
          <indexterm class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>Proxy host port number</tertiary>
            </indexterm> The port number your system uses to access the proxy
          server.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Google Translate V2 </emphasis></para>

          <para><emphasis
          role="bold">-Dgoogle.api.key=A123456789B123456789C123456789D12345678
          </emphasis><emphasis role="bold"><indexterm class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>Google Translate V2</tertiary>
            </indexterm></emphasis> If you have signed up for the Google
          Translate services, enter your private Google API key here. Note
          that the key is 38 characters long.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Microsoft
          Translator</emphasis><indexterm class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>Microsoft Translator</tertiary>
            </indexterm></para>

          <para>Make sure that you have a free Microsoft account. You’ll need
          this to sign-in to <ulink
          url="http://datamarket.azure.com/dataset/bing/microsofttranslator#schema">Windows
          Azure Marketplace</ulink> and use the Translator service. Note that
          up to 2M characters per month are free of charge. The two entries
          required are available in your <ulink
          url="https://datamarket.azure.com/account">account page</ulink>
          under Primary account key and Customer-ID:</para>

          <para><emphasis
          role="bold">-Dmicrosoft.api.client_id=</emphasis><emphasis
          role="bold">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</emphasis></para>

          <para>-<emphasis
          role="bold">Dmicrosoft.api.client_secret=XXXX9xXxX9xXXxxXXX9xxX99xXXXX9xx9XXxXxXXXXX=</emphasis></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Yandex Translate</emphasis><indexterm class="singular">
              <primary>Running OmegaT</primary>

              <secondary>Launch script arguments</secondary>

              <tertiary>Yandex Translate</tertiary>
            </indexterm></para>

          <para>Make sure that you have a free Yandex account. You’ll need
          this to be able to obtain and use Yandex Translate API key. API keys
          can be requested using <ulink url="http://api.yandex.com/key/form.xml?service=trnsl">API key request form</ulink>,
          and viewed on <ulink url="http://api.yandex.com/key/keyslist.xml">My Keys</ulink> page.
          </para>

          <para><emphasis
          role="bold">-Dyandex.api.key=</emphasis><emphasis
          role="bold">trnsl.1.1.XXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</emphasis></para>
        </listitem>

      </itemizedlist>

      <para>Arguments can be combined: to launch
      <application>OmegaT</application> with all the examples described above,
      the command would be:</para>

      <para><literal>java -Dswing.aatext=true -Duser.language=pt
      -Duser.country=BR -Xmx1024M <application>-Dhttp.proxyHost=192.168.1.1
      -Dhttp.proxyport<emphasis role="bold">=</emphasis>3128 -jar
      -OmegaT</application>.jar</literal></para>
    </section>

    <section id="omegat.command.arguments">
      <title>OmegaT in the command line mode<indexterm class="singular">
          <primary>Running OmegaT</primary>

          <secondary>Command line mode</secondary>
        </indexterm></title>

      <para>The purpose of the console mode is to use OmegaT as a translation
      tool in a scripting environment. When started in console mode, no GUI is
      loaded (so it will work on any console) and the given project is
      automatically processed as requested.</para>

      <section id="console.mode.prerequisites">
        <title>Prerequisites</title>

        <para>To run <application>OmegaT</application> in the command line
        mode, a valid <application>OmegaT</application> project must be
        present. The location does not matter, since you have to add it to the
        command line at the start-up anyway.</para>

        <para>If you need altered settings, the configuration files must be
        available. This can be achieved in two ways:</para>

        <itemizedlist>
          <listitem>
            <para>Run <application>OmegaT</application> normally (with the
            GUI) and specify the settings. If you start
            <application>OmegaT</application> in console mode, it will use the
            same settings.</para>
          </listitem>

          <listitem>
            <para>If you can't run <application>OmegaT</application> normally
            (no graphical environment available): copy the settings files from
            some other <application>OmegaT</application> installation on
            another machine to a specific folder. The location does not
            matter, since you can add it to the command line at startup. The
            relevant files are <literal>filters.conf</literal> and
            <literal>segmentation.conf</literal> and can be found in the user
            home folder (e.g. <literal>C:\Documents and
            Settings\%User%\<application>OmegaT</application></literal> under
            Windows, <literal>%user%/.omegat/</literal> under Linux)</para>
          </listitem>
        </itemizedlist>
      </section>

      <section id="starting.in.console.mode">
        <title>Starting in console mode</title>

        <para>To start <application>OmegaT</application> in console mode, some
        extra parameters have to be passed to it on startup. The most
        important is <literal>&lt;project-dir&gt;</literal>, and
        optionally<literal> --config-dir=&lt;config-dir&gt;.
        </literal>Example:</para>

        <para><literal>java -jar <application>OmegaT</application>.jar
        /path/to/project \</literal></para>

        <para><literal> --config-dir=/path/to/config-files/ \</literal></para>

        <para><literal>
        --mode=console-translate|console-createpseudotranslatetmx|console-align</literal></para>

        <para><literal> --source-pattern={regexp}</literal></para>

        <para>Note that all parameters start with a double - character.</para>

        <para><emphasis role="bold">Explanation:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para><literal>&lt;project-dir&gt;</literal> tells
            <application>OmegaT</application> where to find the project to
            translate. If given, <application>OmegaT</application> starts in
            console mode and will translate the given project.</para>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para><literal>--config-dir=&lt;config-dir&gt;</literal> tells
            <application>OmegaT</application> in which folder the
            configuration files are stored. If not given,
            <application>OmegaT</application> reverts to default values
            (<application>OmegaT</application> folder under user home or, if
            unavailable, the current working folder). Note double -
            character</para>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para><emphasis><literal>--mode</literal>=...-</emphasis>
            <application>OmegaT</application> starts in console mode to
            perform one of the following services automatically</para>

            <itemizedlist>
              <listitem>
                <para><emphasis><literal>--mode=console-translate</literal></emphasis></para>

                <para>In this mode, OmegaT will attempt to translate the files
                in /source/ with the available translation memories. This is
                useful to run OmegaT on a server with TMX files automatically
                fed to a project.</para>
              </listitem>

              <listitem>
                <para><literal>--mode=console-createpseudotranslatetmx</literal></para>

                <para>In this mode OmegaT will create a TMX for the whole
                project, based on the source files only. You specify the TMX
                file to be created with</para>

                <para><literal>--pseudotranslatetmx=allsegments.tmx
                --pseudotranslatetype=[equal|empty]</literal></para>

                <para>The argument <emphasis>pseudotranslatetype</emphasis>
                specifies, whether the target segments are to be equal to the
                source, or left empty.</para>
              </listitem>

              <listitem>
                <para><literal>--mode=console-align</literal></para>

                <para>In this mode, OmegaT will align the Java properties
                files found in the<literal> /source/ </literal>folder of the
                project to the contents found at the specified location. The
                resulting TMX is stored in the <filename>/omegat/</filename>
                folder under the name <filename>align.tmx</filename>.</para>

                <para>Additional parameter is required in this case,
                specifying the location of the target data:</para>

                <para><literal>--alignDir={location of translated
                files}</literal></para>

                <para><filename>alignDir</filename> must contain a translation
                in the target language of the project. For instance, if the
                project is EN-&gt;FR, alignDir must contain a bundle ending
                with _fr. The resulting tmx is stored in the
                <literal>omegat</literal> folder under the name
                <filename>align.tmx</filename>.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><literal>--source-pattern={regexp} </literal></para>

            <para>When mode has been used, this option will specify the files
            to be processed automatically. If the parameter is not specified,
            all files will be processed. Here's few typical examples to limit
            your choice:</para>

            <itemizedlist>
              <listitem>
                <para><emphasis><literal>.*\.html</literal></emphasis></para>

                <para>All HTML files will be translated - note that the period
                in the usual *.html has to be escaped (\.) as specified by the
                rules for regular expressions</para>
              </listitem>

              <listitem>
                <para><literal>test\.html</literal></para>

                <para>Only the file test.html at the root of the source folder
                will be translated. If there are other files named test.html
                in other folders, they will be ignored.</para>
              </listitem>

              <listitem>
                <para><literal>dir-10\\test\.html</literal></para>

                <para>Only the file test.html in the folder dir-10 will be
                processed. Again note that the backslash is escaped as
                well.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><literal>--output-tag-validation-={regexp} </literal></para>

            <para>When mode has been used, this option will specify the files
            to be processed automatically. If the parameter is not specified,
            all files will be processed. Here's few typical examples to limit
            your choice:</para>

            <itemizedlist>
              <listitem>
                <para><emphasis><literal>.*\.html</literal></emphasis></para>

                <para>All HTML files will be translated - note that the period
                in the usual *.html has to be escaped (\.) as specified by the
                rules for regular expressions</para>
              </listitem>

              <listitem>
                <para><literal>test\.html</literal></para>

                <para>Only the file test.html at the root of the source folder
                will be translated. If there are other files named test.html
                in other folders, they will be ignored.</para>
              </listitem>

              <listitem>
                <para><literal>dir-10\\test\.html</literal></para>

                <para>Only the file test.html in the folder dir-10 will be
                processed. Again note that the backslash is escaped as
                well.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><literal>--tag-validation=[abort|warn]</literal><parameter>
            outputFileName</parameter></para>

            <para>This option allows the tag validation in a batch mode. If
            <literal>abort </literal>is selected, the tag validator will stop
            on the first invalid segment. If <literal>warn</literal> is
            specified, the tag validator will process all segments and write
            warnings about any segments with invalid tags into the file
            specified.</para>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para><literal>--no-team</literal> addresses projects set up for
            team work. Use it if OmegaT is not to synchronize the project
            contents.</para>
          </listitem>
        </itemizedlist>

        <itemizedlist>
          <listitem>
            <para><literal>--disable-project-locking</literal> allows, under
            Windows, to open the same project with several instances of
            OmegaT. By default, under Windows,
            <literal>omegat.project</literal> is locked, and an error message
            is received when trying to open a project already opened in
            another instance of OmegaT. With that option, no locking
            occurs.</para>
          </listitem>
        </itemizedlist>
      </section>

      <section id="console.mode.option.quiet">
        <title>Quiet option</title>

        <para>An extra command line parameter specific to console mode:
        <literal>--quiet.</literal> In the quiet mode, less info is logged to
        the screen. The messages you would usually find in the status bar are
        not displayed.</para>

        <para>Usage: <literal>java -jar <application>OmegaT</application>.jar
        /path/to/project --mode=console-translate --quiet</literal></para>
      </section>

      <section id="console.mode.option.validatetags">
        <title>Tag validation option</title>

        <para>Another extra command line parameter specific to console mode:
        <literal>--tag-validation=[abort|warn].</literal> When this parameter
        is added, tag validation is done prior to translation/aligning. If the
        value is <literal>abort</literal>, then on tag errors the errors are
        printed and the program stops. If the value is <literal>warn</literal>
        then the errors are printed but OmegaT continues.</para>

        <para>Usage: <literal>java -jar <application>OmegaT</application>.jar
        /path/to/project --mode=console-translate
        --tag-validation=abort</literal></para>
      </section>
    </section>
  </section>

  <section id="building.OmegaT.from.source">
    <title>Building <application>OmegaT</application> From Source<indexterm
        class="singular">
        <primary>Running OmegaT</primary>

        <secondary>Building OmegaT from source</secondary>
      </indexterm></title>

    <para>Note that you will need the ant program
    (<emphasis>http://ant.apache.org/bindownload.cgi</emphasis>) to build your
    own version of OmegaT. Unpack the
    <emphasis>OmegaT_3.n.n_Source.zip</emphasis> file and enter the
    OmegaT_3.n.n_Source folder or enter the <emphasis>./omegat/</emphasis>
    folder of the SVN checked out code. Please make sure that a build.xml file
    is present in that folder. Then, on the command line, type:</para>

    <para><literal>$ ant jar release</literal></para>

    <para>This will create a full distribution of
    <application>OmegaT</application> in the ./dist/ folder, where you will
    find all the files necessary to run
    <application>OmegaT</application>.</para>
  </section>
</chapter>