[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Translating the Emacs manuals (a summary)
From: |
Jean-Christophe Helary |
Subject: |
Translating the Emacs manuals (a summary) |
Date: |
Fri, 19 Jan 2024 18:00:34 +0000 |
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.
- Translating the Emacs manuals (a summary),
Jean-Christophe Helary <=