Translating the Emacs manuals (a summary)

[Jean-Christophe Helary <jean.christophe.helary@traductaire-libre.org>]

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.