Practical Advice for Translators
Here is some advice we collected for translators:
-
Only commit translated files in your language's directory.
The build process is responsible for adding English
files in place of the files you have not committed.
-
Do not commit translated files into the English tree.
Double check your files before committing, to be sure
that you are committing to the right place.
-
Use a system to coordinate with the translators
in your language. Currently we have two systems
used in parallel, the Translators files and the
Revision comments. See the section about
revision
tracking to learn more about this subject.
-
While translating, you will find errors in the
English manual. If you are sure about an error,
that should be corrected, please correct the
found errors yourself. If you are not sure,
whether you found an error or not, please ask
on the phpdoc mailing
list.
-
We have the global entities used all over
the manuals in global.ent.
If you would like to define entities only used
in your language, an ideal place for these
is your_language/language-defs.ent.
See hu/language-defs.ent for
an example.
-
Do not translate entity names, such as &true;
or &return.success;. These are there to be
replaced by their relevant text. Translating them
only cause errors. Similarly do not translate any
tags (eg. <computeroutput>) to your language.
The contents of comments (eg. the bottom of every
file) are also not to be translated.
-
Always make sure, that the modifications you
made to your language's files, are correct.
You may introduce illegal characters. Please
always do a make
test before committing. Introducing an
error in your language's manual can stop the
automatic updates online until you correct the
error.
-
If a documentation build process sends an error
report to the translation mailing list, examine
the problems, and try to fix them before the next
build. If you have 'cross reference to paragraphs
not supported' errors, you probably have old
translated files around. Since paragraphs are
generated by the build system for the missing ids
not yet in those old files, these errors are
inevitable. Either update your translation, or
remove the offending files, thus allowing the
English originals to take precedence.
