Translating the Emacs manuals (a summary)

[Jean-Christophe Helary]

I’m trying here to make a summary of the discussions that we’ve had so far, in 
the hope of being able to propose a proper readme file at some point in the 
close future.

I hope I've not forgotten anything.

JC

---
# Translating the Emacs manuals

## Location

Translated manuals sources are located in the ’doc/lang’ directory, under the 
directory whose name corresponds to the translated language.

For ex. French manual sources are found under ’doc/lang/fr’.

The structure of the language folders should match the structure of the English 
manuals (i.e. ’misc’, ’man’, ’lispref’, ’lispintro’, ’emacs’).


## Format

The translated manuals should be in the same format as the English sources: 
TexInfo.


### TexInfo specific issues

Until Emacs/TexInfo provide better solutions, here are a few rules to follow:

- ’@node’ items should be translated but should be accompanied by an ’@anchor’ 
that contains the original English ’@node’ contents.

- ’@documentencoding UTF-8’ is automatically included in the file since it is 
in ’doc/emacs/docstyle.texi’. Do not add it to your file headers.

- You should add a ’@documentlanguage’ directive that includes your language.

For ex. ’@documentlanguage zh’

- ’@author’ can be used for the translator’s name.

Fr ex. `@author traduit en français par Achile Talon`


## Committing the files

Like other source files, translations should be committed to a separate branch 
for revision. Ideally, the branch name should be suggestive of what they 
contain.

For ex: ’origin/translations/emacs-lisp-intro-ar.texi’

Before committing the files for revision, ensure that they have been properly 
checked for spelling/grammar/typography by at least using the tools that Emacs 
provides.

You should also make sure that the TexInfo files build properly on your system.

Once the files are committed, announce the commit to the emacs-devel list so 
that fellow translators can check the file and review it.

## Discussions about translation issues

Translation-related discussions are welcome on the emacs-devel list. 
Discussions specific to your language do not have to take place in English.


## Notes about the original document

During the course of the translation, you will find parts of the original 
document that needs to be updated or otherwise fixed. If you do not intend to 
modify the original documents right away, do not add notes to the original 
documents but rather keep such notes inside your translation as TODO items 
until you action them.


## Translation teams

The number of words in the Emacs manuals is above 2,000,000 words. While one 
individual could theoretically translate all the files, it is more practical to 
work in language teams.

If you have a small group of translators willing to help, make sure that the 
files are properly reviewed before committing them (see above.)


## Translation processes

Emacs does not provide yet tools that significantly help the translation 
process. A few ideal functions would be:

- automatic lookup of a list of glossary items when starting to work on a 
translation “unit” (paragraph or otherwise), such glossary terms should be 
easily insertable at point

- automatic lookup of past translations to check for similarity and improve 
homogeneity over the whole document set, such past translation matches should 
be easily insertable at point

Although the PO format has not been developed with documentation in mind, it is 
well known among free software translation teams and you can easily use the 
’po4a’ utility to convert TexInfo to PO for work in translation tools that 
support the PO format.