Editing Translation (section)

== Multilingual sites ==

In order to customize EPrints you should make several changes to the configuration files. It is a good time to make yourself familiarize with the  [[EPrints_Directory_Structure/eprints3|EPrints3 Directory Structure]]. Certain files are common for all archives &ndash; <span style="color:red;">change these files only if you ''really'' know what your are doing</span>. Other files are repository specific, any change affects that repository only.

Repository-dependent files are below [[EPrints_Directory_Structure/eprints3/archives|archives]], each repository has it own substructure. When creating a new repository, configuration files are copied from [[Lib/defaultcfg_zero/|lib/defaultcfg_zero/]] (or [[Flavours/pub_lib/defaultcfg/|flavours/FLAVOUR/defaultcfg/]] if using a [[EPrints Flavours|flavour]]). Thus making changes in [[Lib/defaultcfg_zero/|lib/defaultcfg_zero]] / [[flavours/pub_lib/defaultcfg/|flavours/FLAVOUR/defaultcfg/]] or below will affect all ''newly created'' repositories of that flavour but will have no effect on existing repositories. Probably you want to make certain changes before creating repositories, e.g. adding further languages to [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang|lib/defaultcfg_zero/lang]] (and also to [[EPrints_Directory_Structure/eprints3/lib/lang|lib/lang]]), changing the default language and available languages in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/cfg.d|/lib/defaultcfg_zero/cfg.d/languages.pl]], correcting files in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/citations|lib/defaultcfg_zero/citations]] and [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/workflows|lib/defaultcfg_zero/workflows]], etc.

In the description below we assume that you've set the repository, and use directories and file names, whenever appropriate, relative to that repository. It should be straightforward to make these changes so that they will have effect for all newly created archives.

=== Selecting the session's language ===

In a multilingual site you probably let the visitors to choose the language of the session. It is determined by the default setting of the browser preferences, but sometimes users want to change this. Manual setting of the session's language can be done by the [http://files.eprints.org/264/ port] of the ''set_language'' script from earlier Eprints versions, and should go into the [[EPrints_Directory_Structure/eprints3/cgi|cgi]] directory. A handy place for the set_language URL is in the menu at the top of the page. As the the default page template is repository dependent, you should edit [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/templates|archives/ArchiveID/lang/en/templates/default.xml]], the English language template for that repository as follows (but see the remarks above):

  &lt;ul class="ep_tm_menu"&gt;
   &lt;li&gt;&lt;a href="{$config{frontpage}}"&gt;Home&lt;/a&gt;&lt;/li&gt;
   &lt;li&gt;&lt;a href="{$config{perl_url}}/set_lang"&gt;Language&lt;/a&gt;&lt;/li&gt;
    &lt;li>&lt;a href="{$config{base_url}}/information.html"&gt;About&lt;/a&gt;&lt;/li&gt;
   ... 
  &lt;/ul&gt;

The template page on other languages should not contain this ''Language'' item as not necessarily will people recognise it. Rather use a button which reverts the language to English, i.e. insert the following into [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/templates|archives/ArchiveID/lang/XX/templates/default.xml]] for all other languages XX except for English:

 &lt;li&gt;&lt;a href="{$config{perl_url}}/set_lang?langid=en"&gt;In English&lt;/a&gt;&lt;/li&gt;

If you want a little more fancy layout, you might consider using  [http://files.eprints.org/40/ flag images] to be copied to the directory [[EPrints_Directory_Structure/eprints3/lib/static/style/images|lib/static/style/images/flags/]]. If you define a phrase (see the [[#Phrases|Phrases]] section) of the form "cgi/set_lang:lang_XX" then the set_lang script will use that phrase to render a link to that language. A typical format could be

  <epp:phrase id="cgi/set_lang:lang_hu"><epc:pin name="link">
      &lt;img src="/style/images/flags/flag_hu.png" alt="[hu]" /&gt; 
       Hungarian</epc:pin>
  </epp:phrase>

=== Setting the language of outgoing e-mail messages ===

By default, all e-mail messages are sent out on the default language of the depository. You might let the users choose their preferred language so that they'll receive messages on that language. The ''lang'' (system) field is defined for all users; the value can be set automatically in 
[[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/cfg.d|cfg/cfg.d/user_fields_automatic.pl]] for example by

 $c->{set_user_automatic_fields} = sub
 { my ( $user ) = @_;
    if( !$user -> is_set( "frequency" ) )
   {
         $user->set_value("frequency","never");
    }
    ## NEW: set default language to the session language
    if( !$user -> is_set( "lang" ) )
    {
         $user->set_value("lang",$user->{session}->{lang}->{id});
    }
 }

and also let the user edit their own preference by inserting the ''lang'' field in the [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/workflows/user|cfg/workflows/user/default.xml]] workflow, say in the personal section:

   <component type="Field::Multi">
      <title><epc:phrase ref="user_section_personal" /></title>
      <field ref="name" required="yes" />
      <field ref="lang"/> &lt;-- NEW!!! edit preferred language --&gt;
      <field ref="dept"/>
      <field ref="org"/>
      <field ref="address"/>
      <field ref="country"/>
      <field ref="url"/>
    </component>

Finally, you might want the default language appear on the user's profile pages. This needs editing the [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/cfg.d|cfg/cfg.d/user_render.pl]] file by inserting the following into the place of your choice (I coose just next to "country"):

  if( $user->is_set( "lang" ) )
  {
       $p->appendChild($session->make_element( "br" ) );
       $p->appendChild($session->html_phrase("user_preferred_language",
                 lang => $user->render_value( "lang" ) ) );
  }

here the new phrase "user_preferred_language" should be defined in one of the phrase files (see the [[#Phrases|Phrases]] section); in it the pin "lang" contains the language itself:

  &lt;epp:phrase id="user_preferred_language"&gt;Preferred language: 
       &lt; epc:pin name="lang"/&gt;
  &lt;/epp:phrase&gt;

<span style="color:red; font-weight:bold">WARNING!</span> While e-mail messages are sent out utf-8 encoded, they are not properly formatted. For non-English e-mails you must apply the "Proper utf-8 encoding for outgoing e-mails" patch from the [[#Patches|Patches]] section. Also, by default, the text version of the e-mail does not contain links. This is also corrected by this patch.

=== Setting document language ===

Each document file has its own language. The same document might be submitted in different languages. In the default Eprints workflow the reference to the language field is commented out; you only has to enable it. It is in file [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/workflows/eprint|cfg/workflows/eprint/default.xml]], stage "files":

 <stage name="files">
   <component type="XHTML">...</component>
   <component type="Upload">
      <field ref="format" />
      <field ref="formatdesc" />
      <field ref="security" />
      <field ref="license" />
      <field ref="date_embargo" />
      <field ref="language" /> &lt;!-- UNCOMMENT! --&gt;
  </component>
 </stage>

The default value is set in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/cfg.d|cfg/cfg.d/document_fields_default.pl]] to the language of the session:

 $c->{set_document_defaults} = sub
 {
        my( $data, $session, $eprint ) = @_;
  ###### HERE:
        $data->{language} = $session->get_langid();
        $data->{security} = "public";
 };

The available language values are listed in [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/namedsets|cfg/namedsets/languages]], you might consider revising this set.
The "undefined" language is rendered as a question mark (?).

You might also want to print the language as well. To this end, edit the [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/citations/document|cfg/citations/document/default.xml]] file. Show the language only when it is set, and the document's mime type is ''text/plain'', ''application/pdf'', ''application/postscript'', ''application/msword'', or ''other''. (For a full list of available mime type see [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/namedsets|cfg/namedsets/document]] )

 <cite:linkhere>...</cite:linkhere>
 <epc:if test="security != 'public'"> ... </epc:if>
 &lt;!-- NEW!!! --&gt;
 <epc:if test="is_set(language) and format.one_of( 'text/plain' ,
     'application/pdf', 'application/postscript', 'application/msword', 'other')" >
    <epc:phrase ref="citation:doc_language">
         <epc:param name="lang">
              <epc:print expr="language"/>
         </epc:param>
    </epc:phrase>
  </epc:if>

and, of course, one has to define the "citation:doc_language" phrase (see below) in all languages. In the phrase definition we have the pin "lang" which contains the document language in the actual language (defined as the phrase "<tt>languages_typename_XX</tt>"):

  <epp:phrase id="citation:doc_language">
    (The document's language is <epc:pin name="lang"/>.)
 </epp:phrase>

<span style="color: red; font-weight:bold">WARNING!</span> The example above works only after you've applied the "Citation phrases with embedded pins" patch in the [[#Patches|Patches]] section.