6.9 Multilingual Sites

G-Cows provides support for multilingual sites. Of course you could simply create a Branch Site (Section 6.8): a multilingual site is nothing but a particular multiversion site.

However, the build in support allows a gradual translation for your sites. Depending on the context this can be a valuable option or not: for commercial sites you probably need a complete translation or no translation at all. Technical or non-profit sites can still gain from a gradual translation of contents. Pages without a translation will be displayed in the default language with, optionally, an additional message for the visitor. This way, you can simply translate a simple message like "Sorry, this page has not been translated yet; reverting to default language (English)" in as many languages you want. Then, you gradually translate pages: users will browse the site and translated pages will be displayed in their language, the others in site's default language.

6.9.1 Infos for Cows-mkgen

Creating a multilingual site is very easy. First, you have to tell Cows-mkgen about the translations you are planning to do: this is done by placing a single line in file Makefile.cm:

translations: transl1, transl2

transl1 and transl2 are simply labels identifying languages; you can have as many languages you want, separated by commas.

Important: the list of intended translations doesn't include the default language; Cows-mkgen assumes your site is written in a given language and only needs to know about translations. As an example, a site written in English, with a Finnish translation, will be created with the following Makefile.cm:

translations: fi

Then, you have to translate pages (not necessary all pages). To do so, simply create a page named after the original one, with the language label as an additional extension. As an example, the Finnish translation for about/about.cws will be stored in file about/about.cws.fi. Note: it's about.cws.fi, not about.fi: this seems to be a very common error).

Of course all this makes sense if you strongly separate contents and layout; if you read the tutorial section (Part II - Tutorial) you'll see that content pages have the following structure:

<cows include ("tmpl_top.cws"); />

  Contents

<cows include ("tmpl_bottom.cws"); />

This way, you only have two lines to copy and paste from various translations.

6.9.2 Makefile for Multilingual Site

Cows-mkgen will browse the directory tree and look for translations. If a given page foo.cws has a translation foo.cws.fi, the generated makefile will provide 2 rules:

In practice all translated pages will be created in subdirectory fi/. Menus, navigation bars, history stack etc, can be translated since variable _LANG=fi is available inside scripts.

If a given page bar.cws doesn't have a translation, the generated makefile will provide 2 rules:

In practice, pages without a translated source file will be created from the original source. Scripts will see variable _LANG=fi so menus, navigation bars, history stacks etc. will be translated. A variable _REVERT will also be defined: the included scripts will know that the page calling them belongs to the Finnish version but has not been translated yet. This information can be used to display an additional message (in Finnish of course ...).

6.9.3 Example of Multilingual Site

First, let me create a very simple site, consisting is 3 pages: index.cws, page01.cws, page02.cws. All pages include a header and a footer. These files can be found in the example archive inside directory ml-01/.

File: lib/tmpl_top.cws

<cows>

type:
<html>
<head>
<title>Page Title</title>
</head>

<body>
endtype;

print ("[ <a href=\"index.html\">Index</a> |");
print ("  <a href=\"page01.html\">Page 01</a> |");
print ("  <a href=\"page02.html\">Page 02</a> ]");
print ("<hr />");

</cows>

File: lib/tmpl_bottom.htm

</body>
</html>

File: lib/nomkgen

The existence of this file tells Cows-mkgen to skip this directory.
Only the existence is checked; content is not read.

File: index.cws

<cows include ("lib/tmpl_top.cws"); />

<p>
This is site index
</p>

<cows verbatim ("lib/tmpl_bottom.htm"); />

File: page01.cws

<cows include ("lib/tmpl_top.cws"); />

<p>
This is page 01
</p>

<cows verbatim ("lib/tmpl_bottom.htm"); />

File: page02.cws

<cows include ("lib/tmpl_top.cws"); />

<p>
This is page 02
</p>

<cows verbatim ("lib/tmpl_bottom.htm"); />

Now, we want to translate the site; let's say, in Italian so we create the following file:

File: Makefile.cm

translations: it

Run Cows-mkgen to create makefile and Make to create pages:

$ cows-mkgen
$ make

cows   index.cws index.html
cows    -p -D_LANG=it -D_REVERT index.cws it/index.html
cows   page01.cws page01.html
cows    -p -D_LANG=it -D_REVERT page01.cws it/page01.html
cows   page02.cws page02.html
cows    -p -D_LANG=it -D_REVERT page02.cws it/page02.html

Of course, the original site and translated one are equal since we have no translations for the moment. If you look at Make's output, you can see that files for the Italian version have been generated from the original sources with the options -D_LANG=it -D_REVERT so we can handle this informations inside lib/header.cws.

Let's translate the site index first (the new version can be found in the example archive inside directory ml-02/).

File: lib/tmpl_top.cws

<cows>

type:
<html>
<head>
<title>Page Title</title>
</head>

<body>
endtype;

ifndef (_LANG)
  language = "default";
else
  language = _LANG;

if (language == "default") {
  print ("[ <a href=\"index.html\">Index</a> |");
  print ("  <a href=\"page01.html\">Page 01</a> |");
  print ("  <a href=\"page02.html\">Page 02</a> ]");
  print ("  *<a href=\"" + "it/" + outputfile ()
         + "\">Go to Italian Version</a>*");
} else if (language == "it") {
  print ("[ <a href=\"index.html\">Indice</a> |");
  print ("  <a href=\"page01.html\">Pagina 01</a> |");
  print ("  <a href=\"page02.html\">Pagina 02</a> ]");
  print ("  *<a href=\"" + replace (outputfile (), "it/", "../")
        + "\">Go to English Version</a>*");
  ifdef (_REVERT) {
    print ("<hr />");
    print ("<p><strong>Sorry, this page has not been translated yet.");
    print ("Reverting to default (English) language<br>");
    print ("Spiacenti, questa pagina non &egrave; ancora stata tradotta; ");
    print ("verr&agrave; visualizzata in lingua originale (Inglese)</strong>");
  }
}

print ("<hr />");

</cows>

As you can see, inside lib/header.cws we use variable _LANG to display index in one language or the other. Moreover, we use variable _REVERT to display an additional message for pages missing a translation. We also provide cross links from one version to another: from a given page you can jump to its translation.

Let's see file page01.html and it/page01.html with the Lynx text browser (remember that they are both created from the same source page01.cws since there's no translation).

File: page01.html


   [ Index | Page 01 | Page 02 ] *Go to Italian Version*
     _______________________________________________________

   This is page 01

File: it/page01.html


   [ Indice | Pagina 01 | Pagina 02 ] *Go to English Version*
     _______________________________________________________

   Sorry, this page has not been translated yet. Reverting to
   default (English) language
   Spiacenti, questa pagina non č ancora stata tradotta; verrā
   visualizzata in lingua originale (Inglese)
     _______________________________________________________

   This is page 01

As you can see, page it/page01.html has a translated index and a message telling about the missing translation.

Finally, let's translate pages page01.cws; The new version can be found in the example archive inside directory ml-03/. Simply create the following file.

File: page01.cws.it

<cows include ("lib/tmpl_top.cws"); />

<p>
Questa e' la pagina 01
</p>

<cows verbatim ("lib/tmpl_bottom.htm"); />

Run Cows-mkgen again to update Makefile and Make to update pages:

$ cows-mkgen
$ make

cows   index.cws index.html
cows    -p -D_LANG=it -D_REVERT index.cws it/index.html
cows   page01.cws page01.html
cows    -p -D_LANG=it page01.cws.it it/page01.html
cows   page02.cws page02.html
cows    -p -D_LANG=it -D_REVERT page02.cws it/page02.html

As you can see, once you translate a page, Cows-mkgen take care of details: output page it/page01.html is now created from page01.cws.it (no more from page01.cws) and option -D_REVERT is no longer passed to Cows. So, the additional message warning about the missing translation is automatically removed from this page:

File: it/page01.html


   [ Indice | Pagina 01 | Pagina 02 ] *Go to English Version*
     _______________________________________________________

   Questa e' la pagina 01

This manual can be downloaded from http://www.g-cows.org/.