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.
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.
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:
the standard rule for generating foo.html from source foo.cws with the usual command cows foo.cws foo.html
a rule for generating fi/foo.html from source foo.cws.fi with the command cows -p -D_LANG=fi foo.cws.fi fi/foo.html
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:
the standard rule for generating foo.html from source foo.cws with the usual command cows foo.cws foo.html
a rule for generating fi/foo.html from source foo.cws with the command cows -p -D_LANG=fi -D_REVERT foo.cws.fi fi/foo.html
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
...).
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 è ancora stata tradotta; "); print ("verrà 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/.