App_TeamProjects.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"../../../docbook-xml-4.5/docbookx.dtd">
<appendix id="appendix.TeamProjects">
  <title>OmegaT Team Projects<indexterm class="singular">
      <primary>OmegaT</primary>

      <secondary>Team projects</secondary>

      <seealso>Team projects</seealso>
    </indexterm></title>

  <section>
    <title>Version control - introduction</title>

    <para>The collaborative translation offered by OmegaT is based on the
    functionality of version or revision control, widely used by the software
    community to maintain control of changes to the code of a program and
    allow unimpeded collaboration within the development team. OmegaT supports
    two of the popular version control systems (VCS for short), <ulink
    url="http://subversion.apache.org">Apache Subversion</ulink> (often
    abbreviated SVN, after the command name svn) and <ulink
    url="http://git-scm.com/">Git</ulink>. The advantages of a VC system for
    a team of translators can be summarized as follows:</para>

    <itemizedlist>
      <listitem>
        <para>Several team members can work on the translation project
        simultaneously without interfering with each other</para>
      </listitem>

      <listitem>
        <para>They can share common material, like project translation memory
        and its glossary</para>
      </listitem>

      <listitem>
        <para>Every three minutes by default, 
        an updated version of data shared is available to the rest of the
        team</para>
      </listitem>

      <listitem>
        <para>The system maintains versioning for data shared</para>
      </listitem>

      <listitem>
        <para>Conflicts - for instance alternative translations of the same
        segment or glossary entry - can be monitored, resolved and
        merged</para>
      </listitem>
    </itemizedlist>

    <para>The following terms, to be used in the text below, deserve a short
    explanation:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis role="bold">VCS server - </emphasis>i.e. SVN or Git
        server is the environment where the common material is kept and
        maintained on the net. The server can exist in the local network but
        in the majority of cases it will be available on internet, i.e. via
        URL address. One member of the team, the project administrator, needs
        to be acquainted with handling the server side, i.e. the job of setting
        up the environment, importing the OmegaT project, assigning the access
        rights for the team members, resolving the conflicts, etc.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">VCS client: </emphasis>To interface with
        the server an SVN or Git client must be installed on computers of "project managers"
        involved in the OmegaT project. Very popular clients for Windows
        environment are <ulink
        url="http://tortoisesvn.net/">TortoiseSVN</ulink> and <ulink
        url="http://code.google.com/p/tortoisegit/">TortoiseGit</ulink>. Other
        operating systems (Linux, OS X) offer similar packages.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">repository: </emphasis>the place where the
        shared material is saved and maintained, either on a local access
        network or in Internet. Project members connect with it via their VCS
        client.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">checkout:</emphasis> the operation that
        creates a working copy from the repository to your local computer. The
        server keeps the information on checkouts, so that later commits (see
        below) can be performed in an orderly fashion.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">commit: </emphasis>once a new local
        version of the checked-out material is ready, it can be committed to
        the repository and thus made available to the rest of the team. The
        server makes sure that any conflicting changes, due to two members
        working on the same checked-out contents, will be resolved.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">administrator: </emphasis>the person
        responsible for the creation and maintaining of the repository, i.e.
        taking care of the server side of the task. To avoid any problems, one
        person only should have these rights at least initially.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">user</emphasis>: a member of the team,
        collaborating on the common project.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Sharing a project using SVN<indexterm class="singular">
        <primary>Team projects</primary>

        <secondary>Subversion</secondary>
      </indexterm></title>

    <para>There are two possibilities to run an SVN server: you can install SVN
    on your own server or you can use a hosted service. When using an external
    service you must be aware of the possible implications in terms of
    confidentiality, since you are loading the original document on a server
    outside of your direct control. Alternatively, to avoid this issue you can
    set a private SVN server, for example if you already have an Apache server
    that includes the software in question (e.g. VisualSVN).</para>

    <para>Once the SVN server is available, project managers must
    locally install a SVN client, in order to manage the project contents on
    their computers. For Windows we recommend <ulink
    url="http://tortoisesvn.net/">TortoiseSVN</ulink>. For Mac you can
    download the client for instance from <ulink
    url="https://sourceforge.net/projects/macsvn/">SourceForge</ulink>, For
    Linux see <ulink
    url="http://www.yolinux.com/TUTORIALS/Subversion.html">Subversion Commands and
    Scripts</ulink>.</para>

    <section>
      <title>Creating a repository<indexterm class="singular">
          <primary>Team projects</primary>

          <secondary>Creating SVN repository</secondary>
        </indexterm></title>

      <para>The procedure presented here relies on the free SVN server
      (limited to 2 users) offered by <ulink
      url="http://projectlocker.com/">ProjectLocker</ulink>. Note that the creator
      of the repository has implicitly the administrator rights for the
      repository created. Sign in to the site first or - if it is your first
      time on the site, register for it and note your user name and password
      for the future projects.</para>

      <orderedlist>
        <listitem>
          <para>Create a new project on ProjectLocker</para>
        </listitem>

        <listitem>
          <para>Type the name and description of the repository. (
          <literal>OmegaT</literal> and <literal>OmegaT SL Localization
          </literal>in the example used here)</para>
        </listitem>

        <listitem>
          <para>Choose<guibutton> SVN.</guibutton></para>
        </listitem>

        <listitem>
          <para>Click <guibutton>Create Project</guibutton></para>
        </listitem>
      </orderedlist>

      <para>Open the<emphasis role="bold"> Projects</emphasis> view for your
      account. The URL shown under Project Services will be used by SVN to
      connect clients to the SVN server you have just established. This is
      also the place to add members of the team to the project and assign them
      their rights. Note that the team members have to be registered first,
      before you can add them to the project (Note: in the free version of
      ProjectLocker you are allowed only two users per project).</para>

      <para>Projects can be managed according to your development style and
      needs. Similar as in the case of OmegaT projects, you will need to have
      separate repositories for different language pairs. Within a given
      language pair it is best to keep different subjects and/or clients as
      separate repositories as well. The alternative is to have one single
      repository with subfolders <literal>Project1</literal>, <literal>Project2</literal>, etc.,
      and share the common material via common <literal>tm</literal>, <literal>glossary</literal>
      and <literal>dictionary</literal> folders.</para>

      <para>For the example shown here we decided for the one OmegaT project -
      one single repository for the simplicity reasons.</para>
    </section>

    <section>
      <title>Importing the project to SVN repository - Windows</title>

      <para>The repository is empty at this moment. You create first an empty
      client folder on your disk. Create an empty folder, where you will keep
      your project and right-click on it. Select<guilabel> TortoiseSVN &gt;
      Checkout.</guilabel> The following dialog appears:</para>
 
      <mediaobject>
        <imageobject role="html">
          <imagedata fileref="images/Team_projects_checkout.png"/>
        </imageobject>
		<imageobject role="fo">
          <imagedata fileref="images/Team_projects_checkout.png" width="80%"/>
        </imageobject>
      </mediaobject>
 
      <para>Enter the URL, provided by ProjectLocker, into the field
      <emphasis role="bold">URL of repository</emphasis>. Make sure the field
      <emphasis role="bold">Checkout directory</emphasis> is correct, i.e.
      specifies the empty folder you have created, and press <emphasis
      role="bold">OK</emphasis>. Once the operation has finished, you can
      check the said folder: it should now contain a subfolder .svn and a
      green OK badge on its icon will show, that the contents of the folder
      are up-to-date:</para>

      <para>In the next step, we will add the OmegaT files to the local
      folder. The following files are to be shared among the members of the
      team and thus have to be included in any case:</para>

      <itemizedlist>
        <listitem>
          <para>the omegat project file -
          <filename>omegat.project</filename></para>
        </listitem>

        <listitem>
          <para>the translation memory -
          <filename>omegat\project_save.tmx</filename></para>
        </listitem>

        <listitem>
          <para>the contents of the source folder</para>
        </listitem>

        <listitem>
          <para>the project-specific filters definition -
          <filename>omegat\filters.xml</filename></para>
        </listitem>
      </itemizedlist>

      <para>The administrator may decide to include following folders and
      their contents as well: <filename>tm</filename>, <filename>glossary</filename> and
      <filename>dictionary</filename>. Also
      <filename>ignored_words.txt</filename> and
      <filename>learned_words.txt</filename> in the <filename>omegat</filename> folder may be worth sharing and maintaining on the team
      level. Avoid in any case adding <filename>bak</filename> files,
      <filename>project_stats.txt</filename> and
      <filename>project_stats_match.txt</filename>, in the <filename>omegat</filename> subfolder, as
      they would without any need or profit just bloat the repository. You might want to apply the same to
      the <filename>target</filename> folder and its
      contents.</para>

      <para>After copying the required files into the checkout folder you
      will notice that its icon has changed: the green OK badge has changed to
      a red exclamation sign, signifying the change in the local copy of the
      repository. The following two steps will bring the server version up to
      date:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">add the copied files to the local
          version of the repository:</emphasis> right-click on the local
          checkout folder and select <guilabel>TortoiseSVN &gt;
          Add.</guilabel> In the dialog that opens, leave all options as per
          default and click<guilabel> OK</guilabel>. The Add Finished! window,
          similar to the one below will appear:</para>
 
      <mediaobject>
        <imageobject role="html">
          <imagedata fileref="images/Team_projects_Add.png"/>
        </imageobject>
		<imageobject role="fo">
          <imagedata fileref="images/Team_projects_Add.png" width="80%"/>
        </imageobject>
      </mediaobject>
	  
          <para>The contents of the checkout folder will be marked
          accordingly:</para>

          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="images/Team_projects_checkoutAddFolder.png"/>
            </imageobject>
			<imageobject role="fo">
              <imagedata fileref="images/Team_projects_checkoutAddFolder.png" width="80%"/>
            </imageobject>
          </mediaobject>

        </listitem>
        <listitem>
          <para><emphasis role="bold">commit local changes to the server:
          </emphasis>right-click on the local checkout folder and select
          <guilabel>SVN Commit....</guilabel> The Commit window - see below
          opens. Check the changes to be made - i.e. the folders and files
          added in this case.</para>
 
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="images/Team_projects_initialCommit.png"/>
            </imageobject>
	          <imageobject role="fo">
              <imagedata fileref="images/Team_projects_initialCommit.png" width="80%"/>
            </imageobject>
          </mediaobject>

          <para>Enter an appropriate message into the message window and press
          <guilabel>OK</guilabel>. The Commit window will open and show the
          progress of the commit command. It will first commit the current
          contents to the server repository and then update the local copy of
          the repository - i.e. the contents of .svn subfolder - so that it is
          up to date with the latest repository version.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">update local files from the local
          repository copy</emphasis> - the changes received from the server
          repository reside within the .svn subfolder but not yet in the files
          and folders themselves. To update the local files, right-click on
          the checkout folder and select <guilabel>SVN Update</guilabel>.
          Check the contents of the folder to confirm that the local copy of
          the repository and the corresponding files and folders correspond to
          the latest server version:</para>

          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="images/Team_projects_checkoutSVNupdate.png"/>
            </imageobject>
	          <imageobject role="fo">
              <imagedata fileref="images/Team_projects_checkoutSVNupdate.png" width="80%"/>
            </imageobject>
          </mediaobject>
        </listitem>
      </itemizedlist>
    </section>
  </section>
  <section>
  <title>Using the team project in OmegaT</title>
  <para>Once the team project is setup, team members only need <application>OmegaT</application>
  to access the team project. First, they need to use <guilabel>Project > Download Team
  Project</guilabel>. This will actually do a checkout of the project in a local folder. 
  Credentials are stored, so it isn't needed to enter them each time. Under Linux, if 
  <application>OmegaT</application> is still asking for your credentials, you can checking the 
  <guilabel>Force saving password as plain text</guilabel> checkbox.</para>
  <para>For subsequent use, all is needed is opening the project like any other
  <application>OmegaT</application> project. OmegaT will recognize it is a team project, and will 
    synchronize everything automatically, every three minutes by default.</para>
  </section>
</appendix>