Minor documentation updates

This commit is contained in:
acli 2004-12-30 06:48:19 +00:00
parent 9638aa4638
commit 52e5918b91
4 changed files with 151 additions and 70 deletions

4
misc/translator/Makefile Normal file
View File

@ -0,0 +1,4 @@
all: translator_doc.txt
%.txt: %.html
LANG=C w3m $< > $@

View File

@ -0,0 +1,76 @@
<h1>TRANSLATION TOOL, V3.0:
<br>======================</h1>
<p>
This transation tool should greatly help Koha translators.
It's composed of 2&nbsp;scripts:
<ul>
<li>xgettext.pl, that extracts the texts in a template,
and which is called by the script
<li>tmpl_process3.tmpl, which can do 3 things:
<ul>
<li>create a file with all the "translatable strings" in all files in a directory (& its subdirectories)
<li>update an existing translation file.
<li>rebuild translated templates from english & translation file.
</ul>
</ul>
<p>
Call tmpl_process3.pl --help to get a more detailed explanation.
Some additional explanations are also available by calling
perldoc tmpl_process3.pl.
<h2>HOW TO TRANSLATE Koha:
<br>=====================</h2>
<ol>
<li>Create your translation file:
<blockquote>
./tmpl_process.pl create -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s css_opac_fr_FR.po -r
</blockquote>
<p>(In the above example,
/home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/
contains the English templates in the "default" theme,
and po/css_opac_fr_FR.po is where you want the generated PO file to appear.)
<li>Translate your css_opac_fr_FR.po file
using a text editor or a PO file translation tool.
<li>Create your translated templates:
<blockquote>
./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s css_opac_fr_FR.po -r
</blockquote>
<p>
(In the above example,
/home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/
is where you want your translated templates to be saved.)
<li>Copy images/css files in your new directory (as they are NOT moved by tmpl_process3.pl install).
</ol>
<p>
If something changes in English version:
<ol>
<li>Update your translation file:
<blockquote>
./tmpl_process.pl update -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s po/css_opac_fr_FR.po -r
</blockquote>
<li>Translate your new css_opac_fr_FR.po file.
Look for strings marked as "fuzzy" and strings that are not translated.
<li>Create your translated templates:
<blockquote>
./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s po/css_opac_fr_FR.po -r
</blockquote>
<li>Copy new images/css files in your new directory if needed
</ol>
<h2>WEAKNESSES
<br>==========</h2>
<p>For a somewhat up-to-date list of weaknesses,
please run <code>perldoc xgettext.pl</code>
and <code>perldoc tmpl_process3.pl</code>
and read the BUGS sections.
<h2>COPYRIGHT
<br>=========</h2>
<ul>
<li>Paul Poulain (paul.poulain _@_ free.fr) & Jerome Vizcaino (vizcainj _@_ esiee.fr)
<li>Parts of V3.0 by Ambrose Li (acli _@_ ada.dhs.org)
</ul>

View File

@ -1,75 +1,71 @@
TRANSLATION TOOL , V2.0:
============
This transation tool should greatly help Koha translators.
It's composed of 2 script :
* test-extract.pl, that extracts the texts in a template. It is called by
* tmpl_process.
tmpl process can do 3 things :
- create a file with all sentences all files in a directory (& it's subdirectories)
- update an existing translation file.
- rebuild translated templates from english & translation file.
TRANSLATION TOOL, V3.0:
======================
Call tmpl_process --help to get full explanations.
This transation tool should greatly help Koha translators. It's composed of
2 scripts:
HOW TO TRANSLATE Koha :
============
1- create your translation file :
./tmpl_process.pl create -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s opac.fr -r
2- translate your opac.fr file (english & other_language being separated by a tab, using IGNORE and LIMITED pragmas, see below)
3- create your translated version :
./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s opac.fr -r
4- copy images/css files in your new directory (as they are NOT moved by tmpl_process.pl install)
* xgettext.pl, that extracts the texts in a template, and which is called by
the script
* tmpl_process3.tmpl, which can do 3 things:
+ create a file with all the "translatable strings" in all files in a
directory (& its subdirectories)
+ update an existing translation file.
+ rebuild translated templates from english & translation file.
If something changes in english version :
1- update your translation file :
./tmpl_process.pl update -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -s opac.fr -r
2- translate new your opac.fr file (english & other_language being separated by a tab, using IGNORE and LIMITED pragmas, see below)
3- create your translated version :
./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default/fr2/ -s opac.fr -r
4- copy new images/css files in your new directory if needed
Call tmpl_process3.pl --help to get a more detailed explanation. Some
additional explanations are also available by calling perldoc tmpl_process3.pl.
HOW TO TRANSLATE Koha:
=====================
1. Create your translation file:
./tmpl_process.pl create -i /home/paul/koha.dev/koha/koha-tmpl/
opac-tmpl/default/en/ -s css_opac_fr_FR.po -r
(In the above example, /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default
/en/ contains the English templates in the "default" theme, and po/
css_opac_fr_FR.po is where you want the generated PO file to appear.)
2. Translate your css_opac_fr_FR.po file using a text editor or a PO file
translation tool.
3. Create your translated templates:
./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/
opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/
default/fr2/ -s css_opac_fr_FR.po -r
(In the above example, /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/default
/fr2/ is where you want your translated templates to be saved.)
4. Copy images/css files in your new directory (as they are NOT moved by
tmpl_process3.pl install).
If something changes in English version:
1. Update your translation file:
./tmpl_process.pl update -i /home/paul/koha.dev/koha/koha-tmpl/
opac-tmpl/default/en/ -s po/css_opac_fr_FR.po -r
2. Translate your new css_opac_fr_FR.po file. Look for strings marked as
"fuzzy" and strings that are not translated.
3. Create your translated templates:
./tmpl_process.pl install -i /home/paul/koha.dev/koha/koha-tmpl/
opac-tmpl/default/en/ -o /home/paul/koha.dev/koha/koha-tmpl/opac-tmpl/
default/fr2/ -s po/css_opac_fr_FR.po -r
4. Copy new images/css files in your new directory if needed
WEAKNESSES
=======
I've found some weaknesses (some solvable probably, but maybe some unsolvable)
- HTML::Templates pb :
if there is only a <TMPL* > tag between 2 strings, text-extract sometimes merges both strings, and so can't replace them in the translated template. I've solved all those cases with a <br/> or another HTML statement.
The text-extract2.pl filter attempts to address this problem; it seems that the new filter is now working correctly.
==========
- SHORT STATEMENTS
short statements (like "in") can be replaced stupidly (like in cgi-bin => gives cgi-bdans in french). the workaround has been to replace only complete words (
line 185 of tmpl_process :
$line =~ s/(\W)$text(\W)/$1$subst$2/g;
)
Don't seem to have any side effect.
- WORD exist in FILENAME
words that are in the templates and in a perl script name are replaced !
For example : Search is replace by Recherche in french, thus,giving <a href="cgi-bin/opac-Recherche.pl">, which is wrong...
2 ways to solve this problem, IGNORE & LIMITED pragma.
IGNORE :
if a line in translation file is :
this_original_string IGNORE
it is ignored during translation.
LIMITED :
if a line in translation file is :
this_original_string LIMITED;the_translation_string
The string is translated only if :
* has a > just before
* has <space>title=" just before
* has <space>alt=" just before.
This prevent stupid replaces, at the cost of some missing translation maybe.
- MISSING STRINGS
Maybe some strings that should be translated are missing.
You can add whatever you want in text-extract.pl.
For instance, it extracts :
- standard text
- text in alt="SOMETEXT"
- meta html encoding (8859-1) to enable non european translations.
- DIFFERENT WORD ORDER
Some languages have different word order than English in sentences, or even in dates. For these languages, it is impossible to make a good translation at the moment.
For a somewhat up-to-date list of weaknesses, please run perldoc xgettext.pl
and perldoc tmpl_process3.pl and read the BUGS sections.
COPYRIGHT
======
@ paul poulain (paul.poulain _@_ free.fr) & Jerome Vizcaino vizcainj _@_ esiee.fr
=========
* Paul Poulain (paul.poulain _@_ free.fr) & Jerome Vizcaino (vizcainj _@_
esiee.fr)
* Parts of V3.0 by Ambrose Li (acli _@_ ada.dhs.org)

View File

@ -406,8 +406,9 @@ the gettext format.
=back
Note that this script is experimental and should still be
considered unstable.
This script has already been in use for over a year and should
be reasonable stable. Nevertheless, it is still somewhat
experimental and there are still some issues.
Please refer to the explanation in tmpl_process3 for further
details.
@ -439,7 +440,7 @@ A suitable definition of such a function can be
=head1 SEE ALSO
tmpl_process.pl,
tmpl_process3.pl,
xgettext(1),
Locale::PO(3),
translator_doc.txt
@ -460,4 +461,8 @@ xgettext(1)'s sort option. This will result in translation
strings inside the generated PO file spuriously moving about
when tmpl_process3.pl calls msgmerge(1) to update the PO file.
It sometimes generates strings with spurious leading spaces,
leading to failure to match the strings when actually generating
translated files. The cause of this is not yet known.
=cut