unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Translating the Emacs manuals (a summary)
@ 2024-01-19 18:00 Jean-Christophe Helary
  2024-01-19 19:54 ` Eli Zaretskii
                   ` (3 more replies)
  0 siblings, 4 replies; 28+ messages in thread
From: Jean-Christophe Helary @ 2024-01-19 18:00 UTC (permalink / raw)
  To: emacs-devel; +Cc: help-texinfo

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.






^ permalink raw reply	[flat|nested] 28+ messages in thread

end of thread, other threads:[~2024-02-14 10:29 UTC | newest]

Thread overview: 28+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-01-19 18:00 Translating the Emacs manuals (a summary) Jean-Christophe Helary
2024-01-19 19:54 ` Eli Zaretskii
2024-01-20  4:37   ` Jean-Christophe Helary
2024-01-20  7:34     ` Eli Zaretskii
2024-01-22  3:32       ` Richard Stallman
2024-01-20 15:33   ` Translating the Emacs manuals (a summary) - revision Jean-Christophe Helary
2024-01-20 23:00     ` Stefan Kangas
2024-01-21  2:08       ` Jean-Christophe Helary
2024-01-21 18:16       ` Juri Linkov
2024-01-21 20:01         ` Stefan Kangas
2024-01-21 22:57           ` Jean-Christophe Helary
2024-01-19 20:36 ` Translating the Emacs manuals (a summary) Matthias Meulien
2024-01-20  4:38   ` Jean-Christophe Helary
2024-01-20 18:01 ` Patrice Dumas
2024-01-20 18:08   ` Jean-Christophe Helary
2024-01-21 17:32     ` Patrice Dumas
2024-01-20 18:12   ` Eli Zaretskii
2024-01-22  3:33 ` Richard Stallman
2024-01-22  5:47   ` Jean-Christophe Helary
2024-01-25  3:23     ` Richard Stallman
2024-01-26  0:46       ` Jean-Christophe Helary
2024-01-25  3:23     ` Richard Stallman
2024-01-26  0:52       ` Jean-Christophe Helary
2024-01-27  3:38         ` Richard Stallman
2024-01-27  3:53           ` Jean-Christophe Helary
2024-02-13  2:15     ` Richard Stallman
2024-02-13  2:19       ` Jean-Christophe Helary
2024-02-14 10:29       ` Ralph Lin

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).